Create a gist now

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