- people don't read on the web
- how users read on the web http://www.nngroup.com/articles/how-users-read-on-the-web/
- F shaped pattern (Jakob Nielsen)
- what readers look at
- menaningful text and images
- the begining of paragraphs
- bullet lists
- variations in typeface
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
- 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
- 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