Docs-as-code is an approach to technical documentation that applies software development practices to content: documentation is written in plain text formats, stored in version control, reviewed through pull requests, and built automatically by a CI/CD pipeline.
The core principles of docs-as-code
Documentation is stored in version control alongside or near the code it documents; changes are made through the same review process as code changes; documentation is built and published automatically by a CI/CD pipeline; and the authoring format is plain text, typically Markdown or reStructuredText.
Authoring formats: Markdown and reStructuredText
Markdown is the most widely used authoring format for docs-as-code. It is simple, readable, and supported by virtually every tool in the ecosystem. reStructuredText (RST) is more powerful — it supports cross-references, directives, and extensions — and is the standard format for Python documentation and Sphinx-based sites.
Static site generators
The most popular choices for documentation are MkDocs (with the Material theme), Docusaurus, Sphinx, and Hugo. MkDocs is simple and fast to set up; Docusaurus is well-suited for versioned documentation; Sphinx is the most powerful for large, complex documentation sets.
Version control and review
Git is the universal version control system for docs-as-code. Documentation changes are made in branches and merged through pull requests, which provides a review mechanism and a complete history of changes.
When docs-as-code is the right approach
Docs-as-code is well-suited to developer-facing documentation where the audience is comfortable with GitHub and the documentation needs to stay in sync with rapidly changing code. It is less suitable for large, complex documentation sets that require sophisticated content reuse or multi-channel publishing.
Integrating docs-as-code with DITA
Docs-as-code and DITA are not mutually exclusive. Some organisations use a hybrid approach: DITA for complex, reused content and Markdown for developer-facing documentation. The DITA-OT can publish DITA content to Markdown, which can then be incorporated into a docs-as-code site.
Docs-as-code is a powerful approach for the right context — developer-facing documentation in software organisations with strong engineering culture. For organisations with more complex documentation requirements, it is one tool in a broader documentation strategy rather than a complete solution.