The 7 Deadly Sins of Documentation
summary
Seven concrete failures and fixes: documentation ends up deprioritized so incidents drag on, and a GitHub 2017 survey finds 93% insufficient; separate run books vs technical docs (short inverted‑pyramid run books linked from alerts, longer design docs with concrete numbers), keep docs in one or two repositories (Yelp keeps run books in Google Docs and general docs in a wiki), prefer searchable text over video, add code comments that explain why, archive obsolete docs to S3, and require review by fresh readers.
AI-written summary · about
chapters (21)
- 0:00Start
- 0:49Why Do I Care about Documentation
- 2:12Why Do We Need Good Documentation
- 6:00Prioritize Documentation
- 8:41Documentation Has To Be Treated as a Deliverable
- 9:14Documentation Standard
- 10:07Common Mistakes
- 10:42Notes on Accessibility
- 19:41A Repository Overload
- 20:31The Worst Documentation Is Documentation no One Can Find
- 21:12Duplicate Docs
- 23:06Documentation Overgrowth
- 24:20Make Your Documentation a Priority
- 25:23Virtuous Circle
- 26:25Comment Neglect
- 27:10Reading Code without Context
- 28:38Good Comments
- 33:15Keep Your Audience in Mind
- 34:43Video Addiction
- 35:14Video Is More Engaging than Text
- 41:12Distinction between Searchable and Discoverable
related talks
46mThe 7 Deadly Sins of Documentation
18mTechnical Documentation - How Can I Write Them Better and Why Should I Care?
44mCreating a Culture of Documentation
01h 24mWriting Documentation - Practices and Theory
20mDo Docs Better: Practical Tips on Delivering...
43m"How To Write Tech Documentation That Will Save Your Career"
14mdocs docs docs
30mTechnical Documentation