How to write documentation for users that don't read

Kevin Burke

@derivativeburke

This talk

Why people don't read your documentation
Why your awesome docs aren't solving users' problems
Get more effective at solving your users' problems

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

Jakob Nielsen, "F-Shaped Pattern for Reading Web Content"

What do readers actually look at?

Meaningful text and images
The beginnings of paragraphs (first 3-5 words)
Bullet lists
Variations in typeface (Links, bold, etc)
Code snippets

Source

Usability varies

2.25x improvement

Shorter text
Objective POV
Left-aligned sentence starts

Source

Examples

Transgression: Fixed width text

Transgression: Banner blindness

Transgression: Many fixations per line

Transgression: Search failure

Transgression: Search failure

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:

"Helper Libraries"
"Client SDK's"
"API SDK's"
"Library Bindings"
"Language-specific wrappers"

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

# No one will read the sentences
# above/below the code.
@client = Twilio::REST::Client.new
@client.account.sms.messags.create(
  :from => '+14109341234',
  :to => '+14105557069',
  :body => 'Lester, are we still cops?'
)

Transgression: Context

Assuming environment variable context in a code snippet

Transgression: Context

Transgression: Context

Observance

# Download twilio-ruby from 
# twilio.com/docs/ruby/install
require 'twilio-ruby'

@client = Twilio::REST::Client.new "AC123", "bef"
@client.account.sms.messages.create(
  :from => '+14109341234',
  :to => '+14105557069',
  :body => 'Omar comin!'
)

Observance: Inline code

Transgression: Copy/paste fail

  $ gem install rails

  bash: command not found: $

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, with overlay

search results for ssl error, not your docs

Your documentation just failed.

Transgression: Docs behind a wall

Transgression: PDF's

Observance: WikiHow

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

# From http://hurl.it
post "/" do
  if invalid_url? params[:url]
    error = "That's... wait.. what?!"
    return {:error => error}
  end
end

Different messages for different errors

post "/" do
  if (!params.has_key? :url or 
      params[:url].length == 0)
    error = "Please include a Url"
    return {:error => error}
  end
  if invalid_url? params[:url]
    error = "Url #{params[:url]} is invalid"
    return {:error => error}
  end

  # Do something with the form..
end

Observance

if invalid_url? params[:url]
  error = "Url #{params[:url]} is invalid"
  if !invalid_url "http://#{params[:url]}"
    error += ". Did you mean http://#{params[:url]}?"
  end
  return {:error => error}
end

You can fix these!

Strings are easy to find/change

Takeaways

1. Make your documentation readable

Break up the text often
First 3-5 words of every paragraph are most important
65-90 chars per line is a good guideline

2. Care about SEO

Meta description should describe the content
URL should describe the content
Every page is a landing page
Your documentation should always win
Etc etc... read the Google Guide

Making it better

Look at your product from a user/task-driven perspective
Users should "hire" things you control for most failures
Make error messages explain how to fix the problem
Better yet, solve the problem for the user

Thanks!

Kevin Burke

kev.inburke.com

kev@inburke.com

@derivativeburke

These slides are available at:

How to write documentation for users that don't read

This talk

Not in this talk

People aren't reading your docs because...

No one reads anything on the Internet

Users Scan in F-Shaped Pattern

Jakob Nielsen, "F-Shaped Pattern for Reading Web Content"

What do readers actually look at?

Usability varies

Usability varies

2.25x improvement

Examples

Transgression: Fixed width text

Transgression: Banner blindness

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

Mental models, cont'd

These all refer to the same concept:

Example

Observance: Verbs

Transgression: Context

Transgression: Context

Transgression: Context

Transgression: Context

Observance

Observance: Inline code

Transgression: Copy/paste fail

No good suggestions here

Every user failureis a potential job to be done

A user encounters this error:

What are they going to do?

Your documentation just failed.

Transgression: Docs behind a wall

Transgression: PDF's

Observance: WikiHow

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

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

Every user failure
is a potential job to be done