Create a gist now

Instantly share code, notes, and snippets.

How to Write Documentation for People That Don't Read Kevin Burke #railsConf

RailsConf: documentation tips

ex breaking up content https://help.github.com/articles/generating-ssh-keys

table of content https://devcenter.heroku.com/articles/quickstart

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

Transgression:

  • 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" http://www.twilio.com/docs/api/rest

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 https://developers.google.com/closure/compiler/docs/api-ref

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

##summary

  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

http://kev.inburke.com/slides/documentation/

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment