Improving Your Documentation: A talk for developers who want to write stuff good
summary
Documentation requires three concrete ingredients: knowledge, communication, time. Follow four steps: decide why people come, plan content, make text clear (use verbs, active voice, “you”, no idioms), then proofread and test with a novice. Include a quickstart, contributing guide, complete recipes for create/delete, and error messages that state what happened why it happened and how to fix it. Use practical tools like reStructuredText and Sphinx, Markdown or AsciiDoc, plus linters and spellcheckers to catch consistency and grammar issues.
AI-written summary · about
chapters (13)
- 0:00Introduction
- 0:35The importance of docs
- 3:03Core principles
- 5:36Writing documentation
- 7:48Planning content
- 8:33Grammar and style
- 12:31Achieving clarity
- 17:02Using style guides
- 17:29Optimizing error messages
- 19:16Proofing and testing
- 20:51Documentation tools
- 23:26Empathy and summary
- 24:36Q&A and wrap-up
related talks
01h 24mWriting Documentation - Practices and Theory
39mSave a Dev, Write a Doc!
29mHumanizing Your Documentation
46mTechnically Speaking: Improve your code with documentation
52mTechnically Speaking: improve your code with documentation
33mWhat The Doc?!?! How to Write and Read Documentation That Allows You To Get Sh*t Done!
18mTechnical Documentation - How Can I Write Them Better and Why Should I Care?
37mHumanising Your Documentation