Marcia Riefer Johnston & Dave May - One AWS team’s move to docs as code

AWS’s documentation team moved from Word-and-PDF workflows to “docs as code” in GitHub, cutting publication time and making documentation changes as reviewable and traceable as software changes. The core shift: documentation source files became plain-text, version-controlled artifacts; publishing became automated via CI/CD; and approvals moved into pull requests instead of email chains. The result mattered most for quick starts—deployment guides customers use to deploy AWS architectures quickly—where slow formatting cycles and manual conversions were eating time.

In the earlier process, developers built the quick start and produced a Word-based deployment guide draft. Technical writers then edited the Word document via email back-and-forth, added margin comments, and finally the team published a PDF. That workflow was “miserable” for multiple reasons: formatting broke across Word versions and operating systems (Windows, macOS, and even Linux-based alternatives), and even small edits required manual conversion and upload steps. One example described a chunk of text turning white—effectively invisible—highlighting how fragile WYSIWYG document handling could be.

The team’s first docs-as-code phase (“docs 2.0”) replaced Word with AsciiDoc source files stored in GitHub. Writers and developers edited the same text-based files in VS Code, and GitHub commits became the audit trail for every documentation change. Publishing moved to GitHub Pages, generated automatically from the AsciiDoc sources, so updates to the underlying files flowed straight into the published HTML without manual Word-to-PDF/HTML conversion. Because quick starts are open source, the entire history of documentation edits became transparent to external contributors, enabling pull requests and snapshot comparisons at any point in time.

Docs 2.0 also introduced a tradeoff: documentation changes ran through the same testing pipeline as code changes, so even a typo fix could wait hours for end-to-end code validation. The team also struggled with content structure—generic sections (like AWS costs and licensing) had to be replicated across many guides, and a single “settings” file grew increasingly complex with conditional statements for different languages, marketplaces, and regional constraints.

The next iteration (“docs 2.1”) separated documentation from code testing by moving docs into a dedicated branch (“doc edits”) with its own CI/CD pipeline. That pipeline generated previews on commit and published to GitHub Pages only after approved merges. Structurally, docs 2.1 reduced the number of AsciiDoc files (from 13 to 8) and extracted shared material into a standalone “AWS general information guide,” making individual deployment guides “skinnier.” It also replaced sprawling conditionals with variables and standalone files per doctype and language, so authors could select the relevant pieces without managing a growing matrix of options.

Across both phases, the team’s biggest measurable goal—faster publication—improved substantially. They estimate docs 2.0 cut average writer publication time by about 25% versus the Word workflow, and docs 2.1 could roughly halve throughput time further, though exact quantification was difficult due to many variables. Remaining issues included non-standard permissions across repositories, occasional pipeline stalls requiring CI/CD troubleshooting, and plans for better automated testing/linting, retroactive boilerplate updates, and translation management. In short: documentation became a first-class, automated, reviewable engineering artifact—faster to ship, easier to audit, and less dependent on fragile formatting tools.