Writing Documentation - Practices and Theory
summary
Explains why internal docs fail and gives concrete fixes: make documentation part of definition of done, collect titles from confused users, sort into tutorial / how‑to / explanation / reference quadrants, vote the most painful page, and write it together so the asker, the expert and feedback are all present. Use documentation as code with snippets pulled from unit tests (indie‑snippets) so examples compile. Shows measurable wins — better tests, cleaner code, and new utilities discovered because someone had to explain an edge case.
AI-written summary · about
chapters (13)
- 0:00Introduction
- 1:27Why documentation matters
- 6:06Personal motivation
- 7:29Unit tests vs documentation
- 12:51Documentation improves code
- 21:41Why developers fail to write good documentation
- 27:24Three components of good docs
- 30:13Documentation quadrants
- 41:18Docs as code
- 48:09How-to guide
- 58:35Documentation fests
- 1:07:16Running a documentation experiment with teams
- 1:17:31Summary & Q&A
related talks
18mTechnical Documentation - How Can I Write Them Better and Why Should I Care?
40mDocumentation as User Experience
28mImproving Your Documentation: A talk for developers who want to write stuff good
37mHumanising Your Documentation
33mWhat The Doc?!?! How to Write and Read Documentation That Allows You To Get Sh*t Done!
39mSave a Dev, Write a Doc!
29mHumanizing Your Documentation
29mHumanizing Your Documentation