Category Archives: Conferences

How to Write Documentation for People that Don’t Read

These are my notes from Kevin Burke’s talk at the 2015 Write the Docs conference in Portland, Oregon. Any brilliant ideas in the below text should be attributed to Mr. Burke. Any errors, omissions, or misrepresentations are mine. You can also
watch a video of Mr. Burke’s talk.

Kevin Burke

Eye scans show that users read in an F-shaped pattern, from top left down the left side.

Users don’t look at big blocks of text.

Do this:

  • meaningful text and images
  • starts of paras
  • links
  • bullets

Use bulleted lists, not walls of text.

Bulleted lists perform 125% better (2.25x) than paragraphs for getting people to retain information.

Use the Markdown format for Github READMEs so you can have bold, etc. formatting.

People skip things that look like ads; this means they SKIP BIG RED CALLOUTS.

(NTS: we use this a ton, think about revisiting)

Text can’t be too wide (shows JIRA’s REST API docs as bad example)

Text should be 65-90 characters wide, like books.

(NTS: “information scent”)

Biggest paragraph from Github thing has 2 sentences.

Users are also bad at searching; they also don’t try other queries (“one and done”).

There is often benefit to having subtly different variants of questions around, as people tend to ask and search using different words.

People searched for client SDKs at Twilio as:

  • helper libraries
  • client SDKs
  • API SDKs
  • library bindings
  • language-specific wrappers

Example question: “how do I forward a number to my cell phone?”

Meanwhile, the docs said: “How to do everything with an incoming call”

A user won’t associate this; it’s better to have targeted pages.

No one reads anything above or below code snippets.

Code snippets can often have implicit configuration (env vars, library requires, etc.).

There can also be typos in code snippets.

A lot of people are not familiar with pip/gem/etc., so you have to help them figure out how to use peripheral tools.

Twilio has JS that fills in snippets with your actual credentials so when you copypasta a code sample it’s runnable.

People copy the dollar signs from bash snippets.


every user failure is a potential job to be done

Say you get an SSL error authenticating to the Twilio API.

What are you going to do? Google it!

None of the top google results are your actual docs (SO, blogs, forums, etc.)

(NTS: if your stuff isn’t on google, it doesn’t exist.)

transgression: docs behind a wall

At one point 50% of twilio traffic was from Google.

If you have a login wall, you’re throwing away 50% of your traffic.

transgression: providing pdfs

PDFs are not searchable.

WikiHow stole traffic from Twilio!

If users get an error message from you, put that exact message in your docs.

Error messages should be copypastable into the goog.

Validation as documentation; maybe we can improve the error message.

Suggestion: put the user’s input back into the error message string so your user can see what they passed in to cause the error.

Strings are easy to find/change.


  • break up text
  • first 3-5 words of every para
  • more links
  • care about SEO
  • your docs should always win on google
  • make error messages explain how to fix the problem
  • better yet, solve the problem for the user

Thoughts on the 2014 STC Summit

This is a collection of random thoughts based on my attendance at the 2014 STC Summit earlier this week. I will try to post my more detailed notes from the various individual talks over the next days and weeks.

Lots of proprietary tools, not so much open source

There are lots of proprietary document creation and management tools, and their vendors seem to be well-represented here. Coming from a hybrid tech-writing/programming background, I have to admit that some of the proprietary solutions looked sort of strange to me. Many appeared to be Windows-only to boot.

It seems like there is a lot of opportunity for open-source software to make inroads here. I wonder what it would take to bring the XML-editing capabilities of open source editors like Emacs and Vim up to date (if they aren’t already) to match the capabilities of proprietary tools like Framemaker, Oxygen editor, Madcap Flare, and the like.

There are a few reasons why open source and tech comm could be a match made in heaven. Especially when you consider that whatever improvements in process or tooling you create in open source environments are yours to keep, free of charge, forever. This is definitely not the case in proprietary environments. When you develop your own automation and tooling against proprietary tools, and the vendor breaks stuff, you’re often out of luck.


It turns out that XML and the transformation tools that work on it such as XSLT and friends are pretty powerful. I have been aware of the existence of these technologies but haven’t used them much thus far in my career.

I feel like I understood the appeal of the DITA XML spec/style better after attending a great talk given by Caitlin Cronkhite and Ted Kuster from Salesforce. As I understood them to say, DITA is just a way of structuring your XML into topics that other tools can then use to create your documentation set with minimal repetition on the part of the writer. (I will put up my notes from that talk in another post.)

However, I admit I still don’t fully understand the reason for layering the proprietary environments over the top of the structure provided by DITA. I would probably prefer to author directly in XML using Emacs and nXML-mode. Alternatively, I’d use a markup language, such as a Markdown variant, that could be translated to XML with a script much like my own confluence2html, and build the various document sets I needed using Makefiles.

Key Takeaway: Do More Professional Development

The number one lesson from this trip was that I have a lot to learn (this should be evident from the preceding paragraphs). There are so many tools and techniques out there that I am not aware of. I’ve only been at this tech writing gig for a couple of years now, after all.

I look forward to engaging more tech writers working in other industries to learn about how they do what they do. My hope is that this will allow me to develop my own skills by stealing some of their best ideas while sharing some of my own crazy notions as well.