Documentation as Code

Do you know this claim?

I know it very well and like to use it myself. But it only holds under the following conditions:

Fundamentally the claim is simply wrong, because the code can be no more than one part of a software system’s documentation. If it really is written cleanly, though, it can certainly be part of it.

If you want to build software seriously and professionally, there is no way around documentation alongside the code.

Yes, that is true - if it is done wrongly.

First you have to ask WHAT should be documented, second HOW, and third WHY you want to document at all.

Depending on the environment, the requirements can differ considerably. Public sector projects often demand extensive documentation that you simply cannot avoid. Quite simply, because that is how it is. Systems where human lives may be at stake will certainly require different documentation from an administrative application.

Either way: as soon as you have to build a system made of several building blocks, you will think about its architecture - and that belongs in documentation. And if you do it properly, architecture always comes into being before the code.

So from the perspective of a software developer and/or software architect, the WHAT is answered at the very least by documenting the architecture. What that documentation should look like is individual and can differ from project to project. Out of convenience I stick to proven best practices developed by experts, which is why I follow the arc42 structure for architecture documentation. But that is not what this article is about.

So let us turn to WHY I should document anything if the code is the real truth anyway.

My immediate answer would be: not every stakeholder can or wants to read code. Project managers (where they exist), or product owners, may well have access to the code, but they have a very different view of the software they are responsible for.

Documentation therefore has to satisfy more abstract, or simply different, perspectives. Architecture documentation focuses on why the software should be written the way it - hopefully - was written (making sure of that is a different discipline within the software development process). It documents various requirements and connects them to strategies and decisions that should ultimately be reflected in the code.

But HOW should you document so that the team actually maintains it and keeps it current?

Well, my experience says there should be as few medium switches as possible, so that developers document too - ideally even willingly. Which means: the closer to the code, the better.

I therefore try to write all documentation in ASCII format (as the code is) and to store it as close to the code as possible. Where it is possible and sensible, even in the same source repository.

Is that already Docs-as-Code?

NO.

Neither the storage location nor the medium is what decides whether something is Docs-as-Code - even though some media are certainly better suited to really living Docs-as-Code than others.

But I can live Docs-as-Code in a Git repository just as well as in Confluence or a similar platform.

That is, I try to keep a recognisable structure. I try to honour the Single Responsibility Principle in documentation too. And I try to avoid duplication and to write nothing that is not needed (YAGNI).

One further, very important aspect also helps me decide which medium to use (sadly this is not possible in many client projects, even though I do try to influence it): write once, deliver anywhere. In the context of documentation this is, in my view, often underestimated - but it becomes absolutely essential at the latest when I have to deliver my documentation, or make it available to different stakeholders from different departments or even different companies.

So it has to be possible for me to write my documentation once and then present it as a website or send it as a PDF, for example. And the quality should not really differ between the two (the browser’s print function will not normally produce a satisfying result).

On top of that come the different views. I have to be able to prepare my documentation so that, depending on the requirement, it also leaves things out. For instance, you may not want department names to appear in the PDF you send to an external service provider - but you very much do want them in the internal company wiki where the documentation lives. Perhaps even with a direct link into the department intranet, which you would have no access to from outside.

So a number of different forces act on documentation:

To achieve all of that, real code has to be written in the documentation around the actual documentation. Usually these are macros interpreted while the output format is generated. But pre-processors may be needed as well, which may first have to scan the documentation in order to generate additional artifacts.

So anyone who takes documentation seriously, and holds their software (and therefore their documentation) to a certain standard of quality, will not get around thinking about it at the level of a software developer.

This very site can serve as a direct example. It really only presents static content (much like documentation). But it represents me in different views. It also contains my CV (de), for instance. Besides the fact that the CV holds information that can also be found on the website, I want to present the CV both as a website and as a directly downloadable PDF. The CV downloaded straight from the website should not, however, contain personal data such as an address or a telephone number. For that case I want to be able to generate a different PDF on demand - from the same content, but with additional material.

This site is written in ASCIIDOC. Accordingly, there are macros that help me decide which content is shown when, and how.

Here my skills matrix (de) should only be embedded when the output format is PDF.

Elsewhere the matrix is only embedded when the output format is HTML:

You can see it: different places (views), same document being embedded.

And since I can present the matrix a little more fancily on the website than in the PDF, I decide once more within the document itself which form should be embedded.

So: different audience, different presentation.

The pipeline for documentation can of course differ in its details. That depends heavily on the environment. The following picture shows, as an example, the pipeline for this website:

The build system is visible as the central component. This website is built with Gradle and asciidoctor. That can of course vary. There could be other frameworks around or in front of asciidoctor, such as the docToolchain. The idea, however, is always the same:

Documentation rarely fails because people do not want to document. It usually fails because the process does not fit the way they work day to day.

The Docs-as-Code approach tries to solve exactly that problem: documentation is written where the code comes into being, with the same tools, the same principles and the same automation.

That way documentation does not become an annoying extra task - it becomes a natural part of software development.