Code First Docs: How we Threw Out The Book & Put Code First With Twilio Documentation
summary
Twilio moves documentation to a code-first workflow: short prose (under four sentences) before the first snippet, interactive step-by-step tutorials generated by an npm CLI, deployable to gh-pages and one‑click Heroku demos, and Mixpanel metrics. Results: a click-to-call tutorial shows 3x users, double session length and 3x pages per session. Data rules: >11 sentences before code hurts traffic, <4 boosts engagement 5–10x, and a first snippet over 20 lines causes engagement to plummet.
AI-written summary · about
chapters (10)
- 0:00The problem with docs
- 2:52Information foraging theory
- 3:48Analyzing Twilio's data
- 6:38The impact of prose length
- 9:41Prototyping new experiences
- 13:30Validating the new model
- 15:16Data-driven improvements
- 16:47The Thesaurus tool
- 20:35Launching the new docs
- 24:03Conclusion and call to action
related talks
46mDocumentation That Runs: Bridging Code, Prose, and Interactivity
28mBuilding Empathy-Driven Developer Documentation
49mExplain Yourself! Documentation for Better Code
52mTechnically Speaking: improve your code with documentation
46mTechnically Speaking: Improve your code with documentation
51mWriting the Darn Docs
44mUseful and Beautiful Developer Docs and How to Create Them
51mTechnically speaking improve your code documentation