Skip to content
Software Architecture Guide

Documentation as Code

Explanation

Section titled “Explanation”

Documentation as code (also called docs as code) is a philosophy. You write documentation with the same tools you use to write code. That means plain-text markup such as AsciiDoc, a version control system such as Git, code review, and automated tests.

Version control. Git tracks every change to the text. One toolchain manual notes that this gives you a document management system without extra tooling.

Same workflow as development. Others can fork the docs and send pull requests with their changes. A pull request is a proposed change that teammates review before it is accepted. Because docs follow the developer workflow, a team can block a feature from merging when it lacks documentation.

From text to document in three steps. You write the source. A converter such as Asciidoctor parses AsciiDoc into a document model. It then converts that model into formats such as HTML5, DocBook 5, PDF and EPUB 3. The asciidoctor-pdf plugin produces the PDF output.

Diagrams from text. docToolchain uses the asciidoctor-diagram plugin to create PlantUML diagrams from text. You include the generated file in the document instead of copying it. See the article Diagrams as Code.

Toolchains. docToolchain is a docs-as-code toolchain. It publishes AsciiDoc to HTML, PDF, microsites and Confluence. It uses jBake as its static site generator. It also supports teams who want docs as code but still use a wiki.

Fit with arc42. arc42 works well with this approach. Its AsciiDoc or Markdown templates live in Git. Pull requests review them. docToolchain or any static-site generator builds them. See the article arc42 Architecture Documentation Template.

Example

Section titled “Example”

A team keeps its architecture documentation as AsciiDoc files in a Git repository. A developer changes a service and edits the matching text in the same branch. A teammate reviews both changes in one pull request. After the merge, an automated build converts the text to HTML and PDF.

Trade-offs

Section titled “Trade-offs”

The facts here describe the approach and its tools. They do not list its costs in detail. One point is visible, though. Teams that want docs as code but also use a wiki need a toolchain that publishes to Confluence, and docToolchain supports that. Rules such as blocking merges without documentation also bind the whole team to the same workflow.

Docs-as-code flow from plain-text source to published document

Diagram source 
flowchart LR
  A[Write AsciiDoc text] --> B[Pull request and review]
  B --> C[Merge in Git]
  C --> D[Parse into document model]
  D --> E[Convert to HTML, PDF, EPUB]
  E --> F[Publish]

Checks

Section titled “Checks”
  • Documentation sources are plain-text markup (for example AsciiDoc or Markdown) kept in a version control system such as Git.
  • Changes to the documentation are proposed and reviewed through pull requests.
  • Documents such as HTML or PDF are built automatically from the text sources by a toolchain.
  • Diagrams are generated from text and included in the documentation instead of being copied.
Section titled “Related”

Sources

Section titled “Sources”