Humanizing Your Documentation
summary
Argues documentation must be use-case driven, not dry reference, with docs started alongside feature design so users learn goals not controls. Cites Slack examples, Django Girls notes and Contentful style goals; tests linters like Alex.js and Hemingway app to catch insensitive or bloated prose. Calls out a surprising finding — over 92 million instances of the word "simply" on GitHub — and shows concrete fixes: clearer error text, troubleshooting steps, and explicit caveats when a tool doesn’t fit a use case, improvements that demonstrably reduce confusion.
AI-written summary · about
chapters (18)
- 0:00Introduction
- 0:48Meet Carolyn
- 1:08Why write docs
- 3:40Docs for humans first
- 7:16Use case problems
- 8:18JavaScript docs struggle
- 10:23Why hate docs
- 11:30Treat users as people
- 12:54Common doc pitfalls
- 14:21Fixing doc structure
- 16:27Helpful error messages
- 19:23Avoid insensitive language
- 21:31Problem with 'simply'
- 23:16Plain language in docs
- 25:08Avoid insider jargon
- 26:32Being transparent about limitations
- 27:35Honest helpful docs
- 28:18Q&A
