NEW IT Engineering
Published in

NEW IT Engineering

Technical Documentation as Code

Where to store?

This is the simplest question — of course, close to the code — Git.

Which format do we choose?

One of the most important functionalities will be the import of documents into other documents, the reuse. Accordingly, it is essential that this also works across different folder structures.
Asciidoc ( offers exactly this feature and many other design options. In addition, it is machine-writable and readable code.


How do we create higher-level documentation?

Of course, there are documentations that do not belong to one component, but are comprehensive. Fortunately, Git offers a suitable feature to connect the different storage locations (for example, repositories of the applications): Git submodules.

How do we structure the documents?

This is the point where I can’t give any meaningful guidelines, basically the more modular the documents are the better. Using Include we can merge arbitrarily over many hierarchy levels.

  • architecture drawings (we will come to that one later)
  • roles and permissions
  • database
  • error codes
  • properties
  • release notes
  • system specification (using the other modules)

How do we create deliverable documents?

Ascii-Doctor provides a Docker image to generate PDF from asciidoc files. You should extend the image to be able to generate with extended features.

RUN apk add graphicsmagick-dev ruby-dev musl-dev gcc
RUN gem install prawn-gmagick
mkdir _gen
docker build — tag asciidoc .
d=$(date +%Y%m%d)
docker run — rm -v $(pwd):/documents/ asciidoc asciidoctor-pdf doc/systemspec/systemspec1.0.adoc -o _gen/systemspec1.0-$d.pdf

How do we create diagrams? can be comfortably edited via IDE plugins and stored as editable SVG or PNG in the code. Gitlab or other source management systems will have plugins or native functionalities to directly display them in GUI — so you can simply import them in Markdown or Asciidoc.

edit mode with Visual Studio Code plugin
include in Asciidoc and preview

How do we generate content?

There are scenarios in which it is worthwhile to generate documentation from code: properties, error codes, database columns, …

| property | description | default
| | name of the application | my supercool application
| application.loglevel | loglevel of the application (INFO,WARN,ERROR) | WARN
| application.mandatory1 | mandatory property of the application | ${mandatory1}

Putting it all together…

We are able to:

  • store the documents next to our code (including version management)
  • generate content from code
  • include content into each other
  • use diagrams and edit in IDE
  • read documents directly within GUI of our source code management platform (for example Gitlab)
  • work with multiple repositories
  • generate deliverables like PDF files



Blog on full-stack and cloud-first development, BigData, AI and more tech topics. Views expressed are those of individual authors.

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store