Skip to content
Olivier CarrèreTechnical writing practice

Checklist: docs-as-code adoption

Reference
Docs-as-codeCI/CD

A checklist for moving a documentation team onto a docs-as-code workflow - version control, text-based formats, CI/CD, and team readiness.

, 1 min read

View as Markdown

Format

Section titled “Format”
  • Content is (or will be) stored in a text-based, non-binary format - see source format. Binary formats (Word, FrameMaker) can’t be meaningfully diffed or merged.
  • The chosen format matches the team’s actual needs: MarkdownA lightweight plain-text markup language in which formatting is written with simple punctuation, such as a leading # for a heading. It is easy to write and to review under version control, but has no schema to enforce structure, so docs-as-code teams rely on templates and automated checks instead. This manual is written in MDX, a Markdown variant.View in glossary → for simplicity, DITA XMLA structured, modular XML authoring architecture built around the concept/task/reference typology and content reuse via conrefs and ditamaps.View in glossary → if genuine Content reuseWriting a piece of information once and using it in several places or deliverables instead of copying it, so that a correction made once applies everywhere. Conrefs, conditional text, and single-sourcing are ways to achieve it.View in glossary → and Single-sourcingGenerating multiple deliverables (PDF, HTML, help formats) from one source, rather than maintaining a separate source per output format.View in glossary → are required - see formats and tools.

Version control

Section titled “Version control”
  • A RepositoryThe place where a documentation team keeps its sources: shared folders, a CMS database, or a version-control system such as Git, which also stores the complete history of every file.View in glossary → exists and its structure has been decided deliberately - see the repository and a single repository?.
  • Writers who aren’t already comfortable with Git have a path to learn it - pairing with a developer, a short internal workshop, or documented common commands. Don’t assume Git fluency by default.
  • A branching approach is agreed on before it’s needed under deadline pressure - see using branches.

CI/CD

Section titled “CI/CD”
  • Documentation builds automatically on every change, the same way code does - see integrating documentation into development.
  • A build failure blocks merge the same way a failing test would - broken docs shouldn’t ship silently.
  • Preview builds let reviewers see rendered output, not just raw source diffs.

Review process

Section titled “Review process”
  • Documentation changes go through the same pull-request review flow as code, not a separate, looser process.
  • The technical review checklist is used consistently, not ad hoc per reviewer.

Team readiness

Section titled “Team readiness”
  • Writers have working local environments (editor, Git client, build tooling) before the migration date, not on it.
  • A rollback plan exists for the old process, in case the new one needs debugging time before it’s trusted for real releases.