Engineering Documentation
summary
Adopts a docs-as-code workflow with content in a public GitHub repo, Sphinx + reStructuredText, and branch-based launches so changes preview as full-site deploys; CI runs build checks, hyperlink checks (full crawl on a Tuesday cron), and Vale linter for prose to enforce trademarks and sentence case; uses mermaid text diagrams, Netlify (migrating to Cloudflare) for fast continuous deployment, and reports ~500 pages under active versioned maintenance.
AI-written summary · about
chapters (21)
- 0:00Intro
- 1:39What engineering is about
- 3:34What documentation is about
- 4:57Colleague enablement
- 7:38Diataxis
- 9:12Style guide
- 10:46Content structure
- 12:49Docs as code
- 14:32Source control
- 17:00Text-based markup & diagrams
- 22:22Tooling
- 26:43Automating a docs platform
- 27:04Continuous integration
- 30:04Vale
- 34:26Continuous deployment
- 35:54Open source operation
- 36:37Contributors
- 38:27Maintainers
- 40:36Engineering documentation
- 41:33Resources
- 42:14Outro
related talks
47mEngineering Documentation
35mBuilding Docs like Code: Continuous Integration for Documentation
44mPushing documentation (so it doesn't hurt anymore)
36mBuilding Docs like Code: Continuous Integration for Documentation
23mTreating Documentation like Code: a Practical Account
31mGREAT BIG ENGINEERING ORG; itty bitty docs team
33mWrite the Docs!
05mDocs as Part of the Product: Open Source Technical Documentation at Scale