What nobody tells you about documentation
summary
Claims that effective docs split into four kinds of documentation — tutorials, how‑to guides, reference, and discussions — and that each must be written and maintained separately. Tutorials are repeatable, concrete lessons that give immediate wins; how‑tos are problem‑oriented recipes; reference must mirror code structure; discussions give design and history. Cites Django and Django CMS docs as examples, warns wikis leak mixed content and recommends structured formats like reStructuredText and the discipline that reference matches code structure for better adoption and maintainability.
AI-written summary · about
chapters (6)
- 0:00Start
- 2:44BETTER DOCUMENTATION WILL MAKE YOUR PROJECT MORE SUCCESSFUL
- 3:59MOST PEOPLE TRY TO CREATE GOOD DOCUMENTATION
- 5:27HERE'S THE SECRET
- 13:54HOW-TO GUIDES guides that take the reader through the steps required to solve a common problem
- 18:57REFERENCE technical descriptions of the machinery and how to operate it
related talks
29mWhat nobody tells you about documentation
01h 24mWriting Documentation - Practices and Theory
36mTo document, or not document that is the question
30mWriting So Your Words Are Read
45mDocs or it didn't happen!
40mDocumentation as User Experience
13mTechnical documentation – how can I write them better and why should I care?
18mTechnical Documentation - How Can I Write Them Better and Why Should I Care?