How to Write Docs for People that Don't Read

"My users don't read my docs!" - this is a perennial problem for a lot of developers. The talk below gives some great tips for dealing with this, which I've attempted to summarize in this post.

It's well-known at this point that documentation is quite a neglected topic - especially for tools internal to a company, where the bar for support and quality is lower. Somehow, we (developers) feel like our time is best spent architecting or writing code, and anything else is a nice-to-have, but I'm trying to consciously move away from that perspective now.


Users don't read

This is common knowledge today, but here's a usability test to help you crystallize this fact. Users don't read, they scan in an F-shape. It goes like this: scan horizontally across the top, then down the left and scan horizontally again after a few lines/paragraphs.

No one reads anything above or below code snippets - people just copy-paste and try to run. Example with 3 points of friction: video link.

What users actually look at (video link):

  • Meaningful text and images
  • Beginnings of paragraphs (first 3-5 words)
  • Bulleted lists
  • Variations in typeface (links, bold, etc)
  • Code snippets

Common transgressions

  • Documentation that looks like an ad. Example: important tip in a bright-red colored box - usability testing revealed that people were skipping right over it even though it answered the exact question they had. (video link)
  • Lines too wide - stick to 65-90 chars. Wide lines necessitate many fixations per line, while narrow ones allow easy scanning down the left edge. (video link)
  • Page content doesn't immediately answer what the title promises. (video link)

Lessons from good real-world docs

  • Lessons from Github help - broken up content, with short sections, big headings and short paragraphs. Auxiliary stuff hidden in collapsible blocks. For walkthroughs, each step is a numbered section. (video link)
  • Heroku - table of contents at top (video link)

Users are also awful at searching

  • StackOverflow example: they used to be very aggressive about closing duplicate questions, but they realized people often search for the same things with completely different words, so they're a little more tolerant about it now. (video link)
  • Use the same terminology in docs that your users use in support queries, to enable effective searches, or at least find a way to link the two. Twilio examples:
    • There are multiple ways to refer to "client SDKs" (e.g., helper libraries, client wrappers, API SDKs). If users can't find what they're looking for, they might just give up. (video link)
    • User asks "how do I forward a number to my cell phone?". Your docs say, "How to do everything with an incoming call" - this answers the question, but is not targeted. Twilio tackled this by making their home page list a bunch of use-cases, and linking them to the right pages, even though many might link to the same page. (video link)

Every user failure is a potential job to be done.

Advice to make your docs better

  • Look at your product from a task-driven perspective - users are trying to get something done, not sit back and read your docs cover-to-cover.
  • Write half the words (or less) compared to conventional writing. (in Jakob Nielsen's usability test, concise writing yielded an improvement > 30% on their defined usability metric)
  • Write scannable docs (in the same usability test, scannable text gave a 47% improvement)
  • If users get an error message a lot, put the exact text in your documentation and make sure searches lead to it. (video link to example)
  • Validation and error messages can serve as documentation. Make error messages explain how to fix the problem.
  • Better yet, solve the problem for the user.

Now go fix your docs!