Humanising Your Documentation
summary
Argues that documentation must show concrete outcomes not features, advocating use-case-driven documentation with examples like “how to drill a hole” instead of UI reference lists. Recommends specific tools and practices: run Alex jeaious to catch insensitive wording, run Hemingway editor for a grade‑8 readability target, prefer live text over screenshot code, use meaningful placeholder names, add skip links, and run automated checks like axe and WAVE. Claims accessibility fixes and focused examples measurably improve task success.
AI-written summary · about
chapters (34)
- 0:00Humanizing Your Documentation
- 1:21Why do we write documentation?
- 1:50USE CASE DRIVEN DOCUMENTATION
- 2:28How to change the direction
- 3:00How to select the right screw
- 3:27Who do we write documentation for?
- 5:39FUNCTIONAL REQUIREMENT DESIGN
- 7:04JavaScript
- 7:52No one wants to read your docs
- 8:26People don't mind reading docs...
- 11:16Insensitive language
- 14:39Be comparative
- 16:01Bloated language
- 16:29Plain language
- 17:32Unexpected errors
- 17:44Address common errors
- 18:54You're in too deep
- 19:57Take a step back
- 20:38Code snippets shouldn't be screenshots
- 21:05for inline
- 21:17for blocks
- 21:55Watch for extra spaces
- 24:20Poorly defined structure
- 24:35Mindful structure
- 25:55HTML - Hypertext Markup Language
- 28:31Skip links
- 30:27Documentation is left out of the conversation
- 30:47Documentation is for developers
- 32:57Test our docs for accessibility
- 34:26Create an accessibility policy for your docs
- 35:33Host an ally hackathon for your docs
- 35:56FINAL NOTE
- 36:28Accuracy and consistency
- 36:42Aim to be honest, helpful and human
