Humanizing Your Documentation
summary
Advocates switching from reference-first to goal-centered docs that start with user goals and parallel feature development, with teams like mnify beginning to adopt the approach; practical steps include using linters such as Alex JS and Vale to flag biased language, running prose through Hemingway Editor to target grade‑8 readability, avoiding screenshot code blocks in favor of copyable snippets, naming variables meaningfully, documenting common errors with troubleshooting steps, and noting that "simply" appears about 92 million times on GitHub.
AI-written summary · about
chapters (18)
- 0:00Introduction
- 1:24Why write documentation
- 3:30Use case driven docs
- 6:59Challenges of change
- 8:23Why docs frustrate users
- 10:32Improving documentation
- 10:52Sensitive language matters
- 13:19Avoiding oversimplification
- 15:07Using linters wisely
- 16:31Humor in documentation
- 17:33Plain language essentials
- 18:57Handling errors clearly
- 20:21Avoiding expert blind spot
- 22:07Code snippets best practices
- 24:58Meaningful variable names
- 25:19Content structure tips
- 26:01Transparency in limitations
- 27:25Honest helpful human docs
related talks
45mUseful and Beautiful Developer Docs and How to Create Them
48mBeyond Words: Crafting User-Friendly Documentation
28mStop writing docs; start helping!
10mWriting effective documentation
21mWriting documentations that don't suck!
20mStop writing docs; Start helping
01h 24mWriting Documentation - Practices and Theory
26mPractice Makes Perfect: Write Accessible Documentation