Explain Yourself! Documentation for Better Code
summary
Explains concrete steps: write a one‑line elevator pitch, use Markdown stored with code in git, and version docs per releases; prefer short active sentences and involve the reader with examples. Add interactivity like embedded JS consoles, Apiary API browsers or CodePen snippets, and test code blocks in CI so examples stay runnable. Automate screenshots using Selenium or headless browsers, lint prose and links, and consider ReadTheDocs or Contentful for rendering and versioned hosting.
AI-written summary · about
chapters (12)
- 0:00Intro
- 1:59What are they trying to achieve?
- 3:31Assume nothing
- 8:13It's not a manual
- 10:28Interactivity
- 14:34Involve the reader
- 18:37Passive vs Active
- 21:02Keep it short
- 23:37Structure
- 25:58Consistency
- 28:01Format and editing
- 39:30Write your own
related talks
29mHumanizing Your Documentation
46mTechnically Speaking: Improve your code with documentation
46mDocumentation That Runs: Bridging Code, Prose, and Interactivity
48mBeyond Words: Crafting User-Friendly Documentation
28mHumanizing Your Documentation
47mThe Art of Documentation and Readme.md
51mWriting the Darn Docs
01h 14mTechnically speaking: Improve Your Code With Documentation