What is Documentation as Code? And why do you need it?

Patrick Roos -

Table of Contents

There's a great blog post by Gernot Starke about the principles and requirements for technical documentation.

Principles of technical documentation
This article collects fundamental requirements for technicaldocumentation, especially software architecture documentation, togetherwith ideas how to *satisfy* those.
INNOQGernot Starke

The blog post contains a very nice overview of the requirements for technical documentation.

Requirements of technical documentation (Source)

Many of these aspects (such as version control, continuous updating, appropriate tools, etc.) implicitly or explicitly propagate the technique of  "Documentation as Code":

What is "Documentation as Code"?

"Documentation as Code" means that your documentation process benefits from the same techniques used in software development.

Some of these techniques are:

  • Storing content in a version control system such as Git
  • Separation of content (e.g. AsciiDoc), configuration (e.g. Asciidoctor) and presentation (e.g. HTML, PDF, ePUB, ...)
  • Use automation for compilation, validation, verification, and publishing (e.g. in your CI/CD pipeline)
  • ...and use your IDE to write technical content ;-)

Example

Author the content

Write, validate and preview your documentation content in Visual Studio Code with the AsciiDoc extension

Convert the content to a publication format like HTML, DocBook, PDF, etc.

Generate the documentation with asciidoctorj
Example HTML Output

Example Documentation as Code Toolchain

The following list shows you an example toolchain to introduce the Documentation as Code technique.

Author: Write, validate and preview your documentation content

AsciiDoc
Plain text markup language for writing technical content

AsciiDoc IDE Plugins

Convert: Documents to the publication formats like HTML, DocBook, PDF, etc.

Asciidoctor
Processing AsciiDoc into a document model and converting it to specified target output

Publish: Build and Deploy documentation artifacts