Engineering Documentation
summary
Company docs move into a code workflow: content lives in GitHub, builds with Sphinx from reStructuredText, uses docs-as-code and continuous integration to run Vale linting, link checks and preview builds on every pull request. Diataxis content types and small style rules keep 88 contributors producing how-tos, references and explainers; mermaid.js provides editable diagrams; deployment is continuous so approved changes go live immediately and audits track who changed what.
AI-written summary · about
chapters (20)
- 0:00Intro
- 2:06What engineering is about
- 4:10What documentation is about
- 5:47Colleague enablement
- 10:02Diataxis
- 13:41Content structure
- 15:57Style guide
- 17:51Docs as code
- 19:13Source control
- 22:00Text-based markup & diagrams
- 26:57Automating a docs platform
- 27:20Continuous integration
- 33:53Vale
- 37:27Continuous Deployment
- 39:10Open source operation
- 41:29Contributors
- 43:10Maintainers
- 45:38Engineering documentation
- 46:08Resources
- 46:20Outro
related talks
42mEngineering Documentation
25mBuilding Docs like Code: Continuous Integration for Documentation
35mBuilding Docs like Code: Continuous Integration for Documentation
35mThe practical implementation of Documentation as Code
44mPushing documentation (so it doesn't hurt anymore)
50mContinuous and Automated Documentation Docs As Code in Practice
45mDocs as Code Fix a poor documentation culture in your organization
59mTransforming your Documentation Process