Documentation That Runs: Bridging Code, Prose, and Interactivity
Talkat Open Source Summit Europe 2025 · on Wednesday, 2025-08-27· at 15:05· Elicium 2B (Elicium Level 1)·
summary
Five years of lessons show documentation that runs lowers onboarding friction by embedding editable, click-to-run examples and letting users break happy paths. A practical level 0–3 interactivity scale guides effort: copyable curl snippets (level 1), in-page sandboxes like Fastly Fiddle (run + assertions), and full editors like Stripe Workbench (customize, see errors, get client snippets). Best practices: use OpenAPI + Swagger/Redoc, provide test keys or staging data, sandbox execution (WASM) and CI that pulls embedded examples and re-runs them to catch regressions.
AI-written summary · about
chapters (16)
- 0:00Introduction
- 1:45Interactive documentation
- 5:19Why interactive docs
- 8:49Four interactivity levels
- 11:38Level zero example
- 11:58Level one copy-paste
- 14:05Level two click-to-run
- 16:10Level three edit-and-run
- 18:59Building interactive docs
- 22:25Documentation thoughts
- 25:36Intelligent code blocks
- 27:01Live demo
- 33:43Quick API wins
- 36:52Key takeaways
- 40:00Resources
- 40:42Q&A
related talks
51mWriting the Darn Docs
49mExplain Yourself! Documentation for Better Code
48mUseful and Beautiful Developer Docs and How to Create Them
42mDocumentation as an application: enabling interactive content tailored to the user
35mDev Experience in Technical Writing: 15 Tips to Boost Developer Satisfaction
46mTechnically Speaking: Improve your code with documentation
35mThe Art of Documentation and Readme.md for Open Source Projects
21mWriting documentations that don't suck!