One AWS team’s move to docs as code
summary
Team moves docs from Word to AsciiDoc in GitHub, uses GitHub Pages and CI/CD to auto-build HTML, separates docs into a doc-edits branch with its own pipeline, consolidates repeated content into an AWS general information guide, reduces files from 13 to 8, and estimates publishing time drops ~25% on first move and roughly 50% after iteration. Early pain: docs ran through slow code tests and occasional stuck pipelines; next steps: linting, boilerplate versioning, translation support.
AI-written summary · about
chapters (22)
- 0:00Intro
- 2:15Docs as code
- 3:40Our story
- 5:27Our publishing process
- 7:56Docs 20 process
- 12:12Docs 20 file structure
- 13:51Docs 20 improvements
- 16:04Docs 20 summary
- 18:30Docs 21 summary
- 23:47Upcoming
- 25:23QR Codes
- 28:39Why docs over markdown
- 29:45Managing collaboration
- 30:54Keeping code current
- 32:50Time saved
- 34:52Its easier to fix things if theyre demonstrably broken
- 35:29How to manage user supplied values
- 36:48Is Docus code worth doing as a lone writer
- 37:54Resistance to leaving Word
- 39:50Timing
- 42:33The downside
- 43:30Outro
related talks
45mDocs as Code Fix a poor documentation culture in your organization
35mBuilding Docs like Code: Continuous Integration for Documentation
40mFrom resistance to adoption: navigating the challenges of docs-like-code
44mPushing documentation (so it doesn't hurt anymore)
23mTreating Documentation like Code: a Practical Account
42mEngineering Documentation
47mEngineering Documentation
05mDocs as Part of the Product: Open Source Technical Documentation at Scale