How to Write Documentation for People That Don't Read
summary
Users scan pages in an F‑shaped pattern so short scannable lines, clear headings and one‑page quickstarts matter; a formatted rewrite yields a 125% improvement in recall; about 45% from Google land straight on docs so indexable HTML beats PDFs or login walls. Code samples fail in three failure modes (missing requires, env vars, typos) and shipping a bundled cert list or an installer script removes whole classes of errors. Practical fixes: expose error text in docs, publish language‑specific examples, and shorten lines to 65–90 characters.
AI-written summary · about
chapters (29)
- 0:00Intro
- 3:12F-Shaped Pattern
- 4:00What do readers actually look at?
- 4:44Usability varies
- 6:37Transgression: Fixed Width text
- 7:27Transgression: Banner blindness
- 8:09Transgression: Many fixations per
- 8:43Observance: Breaking up content
- 9:25Observance: Table of Contents
- 10:49Searching, cont'd
- 11:35Mental models, cont'd
- 13:29Jobs to be done
- 17:17Transgression: Assuming Linear style
- 18:24Transgression: Assuming context
- 20:16Transgression: Copy/paste fail
- 21:25How can you find out what your users are trying to do?
- 22:18Observance: Inline code
- 22:47Observance: Verbs
- 24:16Example 2
- 26:10Transgression: Docs behind a wall
- 27:02Transgression: PDF's
- 27:50Observance: Error reference page
- 28:34Observance: WikiHow
- 29:41Certificate verify failed
- 30:37Observance: RVM
- 32:07Transgression: Confusing error message
- 36:271. Make your documentation readable
- 37:362. Care about SEO
- 38:23Making it better
related talks
06mHumanizing Your Documentation
01h 24mWriting Documentation - Practices and Theory
37mHumanising Your Documentation
51mWriting the Darn Docs
29mHumanizing Your Documentation
28mHumanizing Your Documentation
51mTechnically speaking improve your code documentation
28mImproving Your Documentation: A talk for developers who want to write stuff good