How to write documentation for users that don't read

Kevin Burke

@derivativeburke

This talk

Not in this talk

Zoolander

People aren't reading your docs because...

No one reads anything on the Internet

nation-shudders

"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?

Source

Usability varies

Usability varies

2.25x improvement

Source

Examples

Transgression: Fixed width text

Transgression: Many fixations per line

Transgression: Search failure

Quickstart

Transgression: Search failure

Quickstart

Observance: Breaking up content

Observance: Table of Contents

Users don't read...

Source

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

Source

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:

Example

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

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

Observance

You can fix these!

Strings are easy to find/change

Takeaways

1. Make your documentation readable

2. Care about SEO

Making it better

Thanks!

Kevin Burke

kev.inburke.com

[email protected]

@derivativeburke


These slides are available at:

kev.inburke.com/slides/documentation

/

#