DaC: Documentation-as-Code -Improving the documentation of the Corona-Warn-App

Improving the Corona-Warn-app documentation with automatic checks

by Johannes Amorosa | June 29, 2020

As you may have heard, the German Government contracted several big IT-Players to develop an App to track citizens with potential Covid-19 infections. There were weeks of headline discussions all over the country and of course on the internet.

We didn’t dare to join this discussion since it’s not our expertise, nevertheless, we at Endocode do like Open Source and the German Government shared the code on Github. How cool is that!

This is not just the only sane way to gain trust in this tracking app, it also allows everyone to find bugs and potential vulnerabilities. Read this article from 1998 if you want more information on why Open Source matters or just ask us.

So what can Endocode do, to help the effort to fight Covid-19?

Since what we do is build Infrastructure, Automation and IT-workflows we found a simple way to create value, by helping reviewers and any other interested party to understand the objective of the code and the underlying algorithms.

We saw that the documentation repository on Github is still a very rough place. It lacks a unified markup and no automation to rectify this is in place. As we do a lot of documentation for our customers, we have a simple NPM based workflow and tooling to help get all documentation in good shape.

On every git commit, several integration jobs are triggered to verify that the new documents are validated against standards and fulfill the quality requirements anyone would expect.

Johannes, Cloud Architect @Endocode & big-time documentation lover integrated a markdown linter, a link follower (to report if a link is broken) and probably the most important one: a spell checker. At the last minute Johannes added a detector to catch insensitive, inconsiderate writing utilizing alex. All these measures should help to improve the quality of the documents.

You may think you heard this from software development and you are right, we think software documentation is part of the code and should be treated like that, with all the automatic checks a software developer would expect. And why not use computers and a continuous integration system like Github actions to verify if your documentation-as-code is on par with your software stack.

See the Pull Request if you want to comment and improve on our combined efforts!

CWA-ci-pipeline