Humanizing Your Documentation
summary
Argues for documenting from goals not UI, shows the use-case-driven docs pattern with a Slack crawl and a drill example, gives concrete linters and tools (alexjs, write-good, Hemingway) and warns they help but do not replace human editing, cites the surprising 92 million GitHub hits for “simply,” calls out concrete fixes: ban vague words, avoid humor, include error explanations, use real accessible code blocks not screenshots, prefer meaningful variable names, add a glossary, and adopt the honest helpful human stance.
AI-written summary · about
chapters (19)
- 0:00Humanizing documentation
- 1:52Documentation goals
- 3:56Humans as audience
- 6:04Use-case-driven docs
- 7:29Problems with reference docs
- 9:59Why developers struggle with documentation
- 11:02Small doc improvements
- 12:06Sensitive language in docs
- 14:37Avoiding easy/simple
- 16:01Linters for inclusive language
- 17:04Humor in docs
- 18:07Plain language for clarity
- 19:30Handling errors in docs
- 20:52Curse of knowledge
- 22:40Code snippets and accessibility
- 24:02Meaningful variable names
- 25:25Structuring docs for users
- 26:28Tool limitations transparency
- 27:35Honest helpful human docs
