You are here

idratherbewriting.com

Post a note under our blog aggregation requests if you want your blog added to our aggregator. Please provide the RSS feed URL and the title of your blog.

Subscribe to idratherbewriting.com feed
Updated: 59 min 42 sec ago

Is the only way to plug into a documentation CCMS through DITA/XML?

Fri, 02/12/2016 - 03:00

After my post the other day about choosing various models for single-sourced content, one person added the following comment:

The beautiful thing about structured authoring with DITA is that you don’t have to make that choice up front. If you’re marking up your content correctly with (more)

Three models for single source publishing — and challenges with each

Thu, 02/11/2016 - 03:00

As I try to wrap my mind around the requirements of one of my current projects, I find myself struggling with the fundamental paradigm of single source publishing.

Consider Project Godzilla, as I’ll call it. Project Godzilla involves an API that plugs in requests from a lot of different product lines, thus serving as a kind of master API for dozens of products. The total possible JSON submitted in the request is quite large, since it accommodates so many potential products. But each customer will only use a slice of the JSON. As a result, the delivery engineers want to give custom (more)

My YAML tutorial in the context of Jekyll

Mon, 02/08/2016 - 03:00

Not many technical writers use YAML in their authoring tools. However, in the Jekyll environment, YAML is commonly used as an approach for creating a table of contents and other lists of content.

Most commonly, you store each item in your table of contents in a YAML file. You then iterate through that YAML file using Liquid syntax in order to push each item into a more complex HTML structure.

When I first learned that this is the approach to creating a table of contents in Jekyll, it struck me as odd. But as I have used it for a while now, I’ve found this is the best way t (more)

The third API course from Peter Gruenbaum on Udemy

Mon, 02/08/2016 - 03:00

Peter Gruenbaum recently published a third course on writing API documentation on Udemy. I reviewed the other two courses in previous posts here and here. Peter’s third course is called The Art of API Documentation.

(more)

Upcoming REST API documentation workshop in Sacramento

Mon, 02/08/2016 - 03:00

Here is a description of the API workshop I’m giving in Sacramento:

Workshop on Documenting REST APIs

At its core, REST API documentation focuses on documenting requests and responses. You describe the various endpoints available, their methods, parameters, and other details. And you also document sample responses from the endpoints, usually describing each element and providing sample code.

In this workshop, you’ll learn the basics of REST API documentation. We’ll dive deeply into the following (more)

New section in API documentation course: "The Job market for API technical writers"

Mon, 02/08/2016 - 03:00

In postings for API documentation jobs, you’ll often see requirements like this:

“Ability to read code in one or more programming languages, such as Java, C++, or Python.”

Although your core task may be to document a REST API, most likely there will be numerous client implementations in different programming languages that you will also need to document.

The variety of programming languages creates challenges for technical writers, especially when employers want technical writers, from day one, to already be proficient in every language needed. In this new (more)

Challenges in documenting long JSON objects

Thu, 01/21/2016 - 03:00

I'm now documenting an endpoint in a project at work that includes about 200 lines of code in a JSON object passed in the request body. There are various levels of key-value pairs and additionally nested objects inside the JSON object.

Most API documentation explains the parameters available for each endpoint. Usually the parameters are passed in the endpoint URL or, more common with POST methods, in the request body.

I added a section called Documenting len (more)

How to apply agile processes to manage your life's projects

Thu, 01/21/2016 - 03:00
The challenge of keeping up

At the upcoming TC Camp, during a brief 5-minute feud activity, Marta Rauch and I are going to provide our perspectives on the following question:

How can I keep up with all the tools, technologies, info and other stuff to stay marketable? What happened to the good old days when all you needed to know was FrameMaker?

Admittedly, I can't help but feel caught in the same technological rat race, barely keeping my head above water. I do have some strategies that work somewhat for me, but there is a guy who (more)

The problem with adopting "bleeding-edge" tools

Sun, 01/10/2016 - 03:00
What are the bleeding-edge tools?

In a recent discussion on the Techw-l listserv, an academic was looking to find advice about the "bleeding edge" trends in help authoring tools. Academics want to prepare students to succeed in the job market once they graduate, and since academics usually aren't focused on tools, this person was looking for guidance.

One of the commenters on the thread made a particularly astute observation about bleeding-edge tools. (more)

Spec-driven Development with RAML — presentation by Michael Stowe to STC Silicon Valley chapter

Sat, 01/09/2016 - 03:00
Slides

Here are Michael's slides:

RAML for Tech Writers from Michael Stowe

Audio recording

Here's the audio recording:

You can also download the MP3 file directly.

(Next time we'll record the video too.)

Spec-driven development presentation descript (more)

First video for API documentation course -- your feedback?

Thu, 01/07/2016 - 03:00

Here's the first video for my API documentation course:

Since I'm planning to make a lot more videos somewhat like this, I want to make sure I'm doing them right.

My Setup

Here are a few details of my setup.

  • iPhone 5 camera mounted on tripod at eye-level
  • Audio recorded separately on 48Khz using Zoom recorder with phantom-powered lapel mic
  • ProCamera app with background exposure set to 2
  • 3 point lighting syst (more)

Why is the TC Camp Unconference format so popular? Interview with Liz Fraley, TC Camp Founder

Wed, 01/06/2016 - 03:00
About the TC Camp Unconference

The TC Camp Unconference is just around the corner. Held January 22-23, 2016, in Santa Clara, California, this conference has been growing in popularity due to its unique unconference format.

The TC Camp Unconference doesn't include any pre-scheduled sessions or speakers. (Although there are some morning workshops available, these aren't part of the unconference format.)

For the unconference, attendees cast their votes on a wide range of topics. The org (more)

Are technical writing blogs growing or dying?

Tue, 01/05/2016 - 03:00
"Blogging is dead"!!???

Every so often someone either proclaims that blogging is dead or asserts that blogging is alive and well. Recently someone noted that the 2015 vs. 2014 statistics comparison graph in my 2015 top posts analysis post looked interesting, so I decided to explore this comparison a little more to try to assess whether blogging (particularly my technical writing blog) was growi (more)

What is the technical writer's role in content marketing?

Mon, 01/04/2016 - 03:00
Hearing a lot lately about "unified customer experience"

This past year I've been hearing a lot about addressing the whole customer journey, or developing a unified customer experience strategy. Companies need to have consistent content for every touchpoint with the customer, from the time the users are prospects to the time those users become customers.

When users are exploring a company, they may listen to a webinar, watch an overview video, explore a demo site, (more)

Analyzing top posts on my blog during 2015 — branding or readership?

Fri, 01/01/2016 - 03:00
Analysis overview

Every year I try to analyze the top posts on my site so that I better understand what information people are looking for. This analysis helps direct my blog efforts and lets me know what's working and not working. This analysis is just as much for me as any reader.

Compare this 2015 post with the Top 10 posts, podcasts, tweets of 2014 -- and what it all means.

Top 10 posts written in 2015

Based on Google Analytics, these 10 posts written i (more)

My 2016 technical writing trends and predictions, or The ripple effects of API growth on technical writers

Tue, 12/29/2015 - 03:00
About trends posts

I have often wondered why posts about "trends" tend to get massive reads. And I think I finally understand why.

One reason we read posts about trends is because we want to know whether our skills are evolving to match the changing technology landscape, so that we'll feel comfortable and secure in the future of our jobs.

If we find that technology is changing more rapidly than we can process, we might need to reorient our skillset, adjust our job functions or focuses, or alter our career direction to better align with the demands of the mark (more)

My upcoming 2016 STC Summit workshop and presentation

Tue, 12/22/2015 - 03:00

My API workshop will more or less follow the same content as my API doc course. This content is online and available right now.

For my presentation on Jekyll, here's the presentation title and description:

Writing tech docs like a hacker with Jekyll

Static site generators are a new breed of documentation tools that are much more common in engineering groups where developers contribute to the documentation.

Jekyll is one of the most popular static site generators, but it is highly simila (more)

Recording of "Creating documentation for startups: Panel discussion" — Write the Docs San Francisco

Tue, 12/22/2015 - 03:00

The four panelists from left to right are Kayce Basque, Daria Hutchinson, Elisa Sawyer, and Richard Mateosian. For more details, see the Write the Docs event description here.

If you just want to listen to the audio only, you can download the MP3 file or listen here:

(more)

How do you stay updated with changes developers are silently making?

Sun, 12/20/2015 - 03:00

A reader asks,

Our documentation team often gets blindsided by changes that developers make. We don't feel like we're kept in the loop with the updates and changes that developers are making to the application. How can we plug into the developer's worfklow?

Developers rarely make changes that aren't tracked in a system like JIRA. (JIRA is probably the most common issue tracking system, but your team may use something similar.) I'm betting they also follow an agile workflow.

My recommendation for plugging into the developer's workflow would (more)

Those pesky authoring tool questions, and an update on my adventures with Jekyll

Sat, 12/19/2015 - 03:00

Last week I attended a Write the Docs meetup in San Francisco, at Atlassian's stylish industrial-urban themed location. About 40 documentation enthusiasts (as they're called in WTD lingo) showed up, and we had an excellent panel discussion about creating documentation for startups.

I recorded the event and will be publishing the videos soon (after I see Star Wars, that is), but I wanted to make a quick blog entry to expand on an enjoyable conversation I had with someone as I was wheeling out my bike to catch the 8:40 Caltra (more)