Skip to content
Olivier CarrèreTechnical writing practice

Adopt docs-as-code

Treat documentation like code: Git, Markdown, pull requests, CI/CD, and static publishing pipelines.

1 min read

View as Markdown

Docs-as-codeTreating documentation like source code: text-based formats, version control, code review, and CI/CD, rather than a separate publishing process.View in glossary → is not just storing documentation in Git. It is an engineering workflow: documentation is written in text-based Source formatThe format content is authored in, as distinct from the target format it's published to — the recipe versus the dish.View in glossary →, kept in Version controlRecording every change to a set of files so that any earlier state can be restored, changes can be compared, and several people can work in parallel. Git is the most widely used version-control system; docs-as-code keeps documentation under version control next to the product code.View in glossary → next to the product, changed on branches, reviewed through pull requests, checked automatically, and published by a pipeline. This section follows the order in which a team usually adopts it: why, Git, 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 → design, branches, then CI/CD (continuous integration and continuous delivery)Automation that checks every change as soon as it is submitted (continuous integration) and publishes the result once the checks pass (continuous delivery). In docs-as-code, a CI/CD pipeline builds the documentation, runs tests such as link and schema checks, and deploys the site.View in glossary → and review.

Why docs-as-code?

Section titled “Why docs-as-code?”
Integrating documentation into developmentAligning release cadence, version control, automated testing, and CI/CD pipelines.

Git

Section titled “Git”
Version control systemsWhy version control matters for documentation, not just code.
Git: from file to contentThinking of Git as a content history, not just a file history.

Repository design

Section titled “Repository design”
The repositoryWhat belongs in a documentation repository, and how to structure it.
A single repositoryThe case for keeping documentation and code in one place.
Which repository for group workChoosing a repository model when multiple writers collaborate.
Shared network directoriesWhy shared drives fall short for collaborative documentation work.
SQL databasesWhen a database-backed repository makes sense — and when it doesn't.
CMS workflow and reliabilityThe workflow benefits of a CMS, weighed against its reliability trade-offs.

Branches

Section titled “Branches”
Using branchesBranching strategies for parallel documentation work.

Source formats and publishing

Section titled “Source formats and publishing”
Source formatChoosing what you write in — the decision that determines your entire toolchain.
DeliveryGetting finished documentation to the people who need it, in the format they need it in.

CI/CD and documentation review

Section titled “CI/CD and documentation review”
A practical CI/CD pipelineBuild, test, link-check, preview, deploy — annotated stage by stage.
A documentation review workflowSplitting technical review from editorial review, and why.
Docs-as-code adoptionFormat, version control, CI/CD, and team readiness.

Working with DITA XMLA structured, modular XML authoring architecture built around the concept/task/reference typology and content reuse via conrefs and ditamaps.View in glossary → or Single-sourcingGenerating multiple deliverables (PDF, HTML, help formats) from one source, rather than maintaining a separate source per output format.View in glossary → instead? See choosing an authoring model. Looking for the text-processing and automation tutorials? See automation & legacy techniques. To see how a docs-as-code site can also serve its content to scripts and AI assistants, see about this manual’s API.