How to write documentation for users that don't read

Kevin Burke


This talk

Not in this talk


People aren't reading your docs because...

No one reads anything on the Internet


"How Users Read on the Web", Jakob Nielsen

Users Scan in F-Shaped Pattern

F-shaped pattern for web content
Jakob Nielsen, "F-Shaped Pattern for Reading Web Content"

What do readers actually look at?


Usability varies

Usability varies

2.25x improvement



Transgression: Fixed width text

Transgression: Many fixations per line

Transgression: Search failure


Transgression: Search failure


Observance: Breaking up content

Observance: Table of Contents

Users don't read...


Users don't read...
and they are awful at searching


Searching, cont'd

There’s often benefit to having multiple subtle variants of a question around, as people tend to ask and search using completely different words, and the better our coverage, the better odds people can find the answer they’re looking for.

Jeff Atwood

Mental models, cont'd

These all refer to the same concept:


Your user:

How do I forward a number to my cell phone

Your documentation:

How to do everything with an incoming call

Observance: Verbs

Transgression: Context

Transgression: Context

Assuming environment variable context in a code snippet

Transgression: Context

Typo in the text

Transgression: Context

Missing import on the first line


Observance: Inline code

Transgression: Copy/paste fail

No good suggestions here

Every user failure
is a potential job to be done

A user encounters this error:

OpenSSL::SSL::SSLError: SSL_connect returned=1 errno=0 state=SSLv3 read server certificate B: certificate verify failed

What are they going to do?

search results for ssl error
search results for ssl error, with overlay
search results for ssl error, not your docs

Your documentation just failed.

Transgression: Docs behind a wall

Transgression: PDF's

Observance: WikiHow

wikihow docs

If users get an error message a lot, put the exact text in your documentation

Observance: Error reference page

Validation as documentation

Transgression: Confusing error message

Different messages for different errors


You can fix these!

Strings are easy to find/change


1. Make your documentation readable

2. Care about SEO

Making it better


Kevin Burke


These slides are available at: