The 7 Deadly Sins of Documentation
summary
Covers seven concrete failure modes and fixes backed by a GitHub 2017 stat that 93% of projects find docs insufficient and by Yelp’s experience creating a style guide and consolidating content into a single Confluence wiki. Distinguishes run books from technical docs, prescribes the inverted pyramid for incidents, requires benign example commands, searchable repos with change history, regular reviews and ownership, clear titles and audience notes, alt text/subtitles and transcripts for media, and routine pruning of obsolete pages.
AI-written summary · about
chapters (12)
- 0:00The importance of good docs
- 3:44Root causes of poor docs
- 6:33Strategies for improvement
- 9:28Burying the lede
- 13:17Technical documentation
- 16:45Repository organization
- 19:47Avoiding overgrowth
- 22:43Code and comment habits
- 26:22Jargon and accessibility
- 30:30Video and media pitfalls
- 34:27Case study at Yelp
- 39:48Summary and Q&A
related talks
43mThe 7 Deadly Sins of Documentation
01h 24mWriting Documentation - Practices and Theory
18mTechnical Documentation - How Can I Write Them Better and Why Should I Care?
44mCreating a Culture of Documentation
29mHumanizing Your Documentation
34mHumanizing Your Documentation
14mdocs docs docs
43m"How To Write Tech Documentation That Will Save Your Career"