One AWS team’s move to docs as code: what worked, what didn’t, what’s next¶
Sketchnote
Description
If you create docs in Word, manually formatting your files and emailing them around, you know that the process can be error-prone and slow. That’s how our team used to do docs. Our team is an Amazon Web Services (AWS) group of developers and tech writers—specifically, the Integration and Automation team. Our docs are guides for Quick Start architectures that help people deploy popular technologies in the AWS Cloud.
In 2020, we switched to a docs-as-code approach, which we dubbed Docs 2.0, using AsciiDoc and GitHub Pages.
- With the use of AsciiDoc, a plain-text authoring format, we streamlined our process in several ways: We incorporated documentation into the same CI/CD pipeline that we used for code. We built a set of files whose content stayed the same across the whole doc set, making that content uneditable so that authors could focus on project-specific information. And we created variables and conditions to allow for flexibility while improving consistency.
- With GitHub Pages, we automatically generated attractive, navigable docs.
Docs 2.0 has streamlined our process. Developers create content more efficiently now that they’re working in a familiar text-based environment. Tech writers no longer have to fix formatting or restore the content that no one was supposed to touch. Also, docs get updated faster since anyone can submit pull requests. Finally, we added translations and spun off various types of guides.
As successful as Docs 2.0 was, we ran into issues.
- Our docs became hard to manage and learn as variables and conditions proliferated.
- Subjecting docs to the same testing as the code created delays and prevented technical writers from independently publishing doc edits.
- Keeping common content in every doc made content maintenance unnecessarily complex.
We’re addressing these issues by further streamlining our files and processes in Docs 2.1.
- Conference: Write the Docs Portland
- Year: 2022
