Skip to content

Instantly share code, notes, and snippets.

What would you like to do?
How to Write Documentation for People That Don't Read Kevin Burke #railsConf

RailsConf: documentation tips

ex breaking up content

table of content

principle: users are really bad at searching

Jobs to be done: Clay Christensen

  • who's using. what's needs are
  • apply the same theory to your documentation
  • ex how do i forward a number to my cell phone?
  • doc: how to do everything with an incoming call


  • Assuming linear style
  • assuming context
    • assumed you've set environment variables
    • typo
    • copy/paste fail

how can you find out what users are trying to do? inline code put varbs eg: "View Call Queues"

every user failure is a potential job to be done if users get an error message a lot, put the exact text in your documentation

  • eg: google error messgae

No PDF, no login wall

Error reference page

fix the problem before it happens RVM

  • Validation as documentation
  • instruct with error messgaes
    • 'please include a url', 'url is not valid'
    • better: "Url is not valid, did you mean xxx"

going further:

  • user testting

let users do simplest thing you can do


  1. make your documentation readable
  • break up the text
  • first 3-5 words of every paragraph are most important
  • 65-90 chars per line is a good guideline
  1. care about SEO
  • meta description should describe the content
  • URL should describe the content

jobs to be done!

  • look at your product from a user/goal
  • users should hire things you control for most failures
  • solev the problem for the user

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
You can’t perform that action at this time.