Hack your documentation!

Any resemblance to reality is pure coincidence … or not

During your career you probably asked once for this kind of questions:

• Where is the documentation?
• Do you remember why we have been designing this component like that?
• Is the documentation up to date?
• Do you have any licence for this design tool (such as MS Visio)?
• How can I validate and share thoughts about pieces of documentation?
• How can I transform writing documentation as a funny task?
• And so on

Beyond of these typical concerns, we can ask ourselves how can we manage efficiently our project documentation nowadays?

In most cases, documentation is formalized through office documents or wiki pages which include diagrams made by Microsoft Visio or any other design tool. Tracking this kind of documents turns out to be really difficult because they are not really designed for that. For instance, for an engineering team, dealing with versions, putting comments and replying to them could be complicated. Even documentation is often tracked by adding a track of version chapter, diagrams are rarely tracked and it’s difficult to see differences between two versions.

In addition to, when we start to code, source code and documentation become independent and inevitably documentation lags behind the code and become outdated and unusable.

Eventually, the most important, perhaps the root cause for developers of these troubles: writing this kind of documentation is boring.
Without a doubt they prefer coding.

Considering your documentation as an artifact

When it comes to project deliverables, we often think about code, scripts, binaries or libraries. However, we often miss one important artifact: the documentation. Usually an application is created and maintained for years. During this maintenance period, there are inevitably a turn over of engineering teams and knowledge can be lost over the years if its documentation is not really followed up.

GIT or any modern SCM

Thus, one of the most appropriate practice, which is widely adopted today, is to store project documentation close to the code, straight in the repository. To illustrate what I mean, I will talk about GIT and GITLAB in this article.

By adopting this practice, you can easily manage your documentation with your code. You don’t have to look for where you have stored the latest design specification, it’s in your repository!

Besides, when you release your code, the documentation will be released in the same time.

Obviously, you can manage binary documents with GIT. However if you put office documents in you GIT repository, you will loose benefits of your versionning system. I will explain how you can do simpler and better.

Less is More

As I said previously, we used to create documentation by filling office documents. But, hold on! Do you really need all the Microsoft Word (for example) processor’s features to create your software documentation? Of course not. By using GITLAB (or GITHUB, BITBUCKET), you can write a minimalistic but insightful documentation by creating Markdown or Asciidoc documents. Their syntax are simple and straightforward. In my opinion, it encourages designers and developers to get straight to the point.

Moreover you can easily add the following mechanisms to your design documents:

• Versioning documentation
• Reviewing modifications using merge requests
• Deploying websites which expose your design
• Generate if it’s necessary PDF documents.

How to implement that?

OK, we know how to store documentation and make it accessible, but what are the most insightful documentation types for project teams and how to create them using “Documentation As Code” paradigm?

In this article, I will introduce the following topics:

• Architecture Decision Records
• Architecture and design documentation

Architecture Decision Records (ADR)

There are plenty of articles talking about architecture decision records. To sum up, ADRs formalized in a markdown (or asciidoc) document all the significant design decisions and exposes the corresponding context and the consequences.

Logging architecture decisions helps developers who maintain the code to keep and track the context of all decisions made during the project. You can find below a template which could be applied in your projects:

# Title 
# Status
- [ ] proposed
- [X] accepted
- [ ] rejected
- [ ] deprecated 
- [ ] superseded

# Context
# Decision
# Consequences

By this way you could answer to the question exposed above : “Do you remember why we have been designing this component like that?”. It’s also another way to keep the knowledge inside the project.

Architecture & design documentation

Usually, when we start coding, we refer to an architecture design. As times goes by, the written or modifed code is differing from the intented architecture at the beginning.

A way to keep architecture design close to the code is to consider architecture design as an artifact and create them using modeling tools such as Structurizr or PlantUML.

These tools enable creating models such as those described by Simon Brown’s C4 Model directly from source files. You can also create UML models (use cases, activity diagrams,… ) in the same way.

For instance you can generate an use case diagram with this bunch of lines:

@startuml
left to right direction
Customer --> (My fantastic use case)

(My fantastic use case) --> RDBMS
(sub use case) .> (My fantastic use case) : includes
@enduml

Then you have to run PlantUML to generate diagrams as PNG, SVG or ASCII art.

You can do the same for any other UML diagrams. Regarding architecture documents, you can either use Structurizr or this extension of PlantUML to create architecture models. At the opposite of Visio diagrams, these diagrams are automatically generated from plain text source code.

You probably understood the benefits of this approach. By creating your models from source code, you can easily version and track them. So much so that seeing differences will never be a problem. Then, you don’t have to worry about managing layout and look and feel. The processor (eg. PlantUML) does it for you!

Validation

If you are convinced to embrace this new way of produce documentation, you should be able to easily review it as you can do with source code.

Actually, you could both validate it automatically and manually. Firstly, you can review documentation during merge requests reviews, share thoughts and remarks with social functionalities of any advanced SCM platform. Next, you can also automatically validate produced documentation. Due to its formalism (plain text files), you can also integrate a validation process using a linter within the project CI build.

For instance, validating markdown documents could be done using David Anson Markdownlint.

By this approach, you can improve the quality of your artifacts in the same way you can do for your source code.

How to publish it?

Last but not least, CI/CD is a good practice of software engineering. Now that your documentation is a part of your source code, you can integrate its creation in your CI/CD process. We talked about validation, but you can also create SVG, PNG from your model source files during your CI/CD pipeline and not storing them in your repository.

This generated content could also be published in a web site. For instance, GITLAB enables producing websites based on MKDOCS or GITBOOK. For GITHUB users, you can create websites using GITHUB Pages.

To conclude

To sum up, you can consider now your documentation as an artifact of your project and improve its quality in the same way than your source code. By using modern SCM platforms such as GITLAB or GITHUB you can automate your production process and improve tracking and communication within your teams.

Eventually, one of the most important benefits you will receive if your adopt “Documentation As Code” will be simplicity. Writing plain text documentation using tools exposed in this article enable to only focus to its substance and not on its form.