Treating your documentation as code is becoming more popular because it allows documentation to be version controlled, reviewed, and managed like code. This approach is referred to as “Documentation as Code” and has many advantages, including:
- Save your documentation in the same code repositories.
- You can rely on Git to version your documentation and make it easier to track changes.
- You can edit your documentation using IDE you are using in your development.
- Automate documentation updates.
- You can generate your documentation in PDF or other formats for business and other non-tech stakeholders.
Which Markup language to use?
With the Documentation as Code approach, the documentation is written in plain text markup languages like Markdown or Asciidoc, which are easy to read and write. The documentation files are then stored in a version control system like Git along with the code.
Markdown
Markdown is a lightweight markup language for creating formatted text using a plain-text editor (Wikipedia).
The following screen shows on the left a simple text with Markdown language and how it is formatted and displayed on the right side of the screen.
Markdown is a lightweight markup language that is easy to read and write but has limited syntax for more complex document formatting. To add more advanced features to your Markdown documents, you can use extensions or variants of Markdown.
AsciiDoc is another alternative to Markup worth considering because of the rich features and more comprehensive syntax that AsciiDoc offers.
AsciiDoc
AsciiDoc is a plain-text markup language for writing technical content. It is more powerful than Markdown when it comes times to writing more complex documents. AsciiDoc files can be translated into many formats, including HTML, PDF, EPUB, and MS Word.
In the following sections, I will show you how to use AsciiDoc to document your architecture.
First, make sure to install an AsciiDoc plugin on your preferred IDE. I am using this plugin on my IntelliJ and this extension on VS Code.
The following is a simple example of an architecture document using the AsciiDoc language.
Use existing open-source template
Instead of creating your asciidoc file from scratch, you can use one of the free open-source templates provided by arc42 as a starting point for your documentation.
The arc42 template includes a set of standard sections and subsections that cover different aspects of software architecture, such as the system context, functional and non-functional requirements, architecture decisions, and more.
You can download arc42 templates in different formats, including asciidoc and markdown here.
Modularize your documentation
Instead of having one large document in asciidoc, you can create several small modules and reference them from the main document using the “include” directive.
This approach allows you to break down a large document into smaller, more manageable pieces and reuse content across multiple documents.
Your documentation composed of modules is more organized, consistent, and reusable, saving time and improving your documentation’s quality over time.
You can download an example of asciidoc doc using modules (arc24) here and adapt it to your needs.
How to use and include diagrams?
Similarly to the documentation, several text-based diagramming tools allow you to create diagrams using plain text, such as PlantUML. These tools use a domain-specific language (DSL) to describe the diagram elements and relationships and generate an image or vector file from that text.
This makes it easy to store diagrams along with your documentation in a version control system and to track changes to the diagrams over time.
PlantUML can be integrated into popular IDEs such as Visual Studio, IntelliJ IDEA, and Eclipse. These IDEs have plugins that allow you to create and view PlantUML diagrams directly within the IDE.
In addition, depending on the diagrams you want to generate, PlantUML needs a working version of GraphViz that you can download here.
The following is an example of creating a component diagram using PlantUML.
The next diagram shows how you can create a simple class diagram.
In addition to PlantUML, several other popular tools and text-based diagramming languages can generate diagrams in your documentation., such as Structurizr and Asciidoctor Diagram.
But how to insert an image in your asciidoc document?
The answer is simple. All you need is to generate your image from the diagram and insert it in your document, as illustrated below.
How to generate PDF, HTML and other format from your asciidoc?
One of the advantages of treating documentation as code, is it can be generated automatically into various formats, such as HTML, and PDF. This can make it easier to maintain documentation and ensure it is always up-to-date and consistent with the application you are building.
You can generate HTML, PDF, MS Word documents, and other formats from your asciidoc documents using AsciiDoctor (already installed when you have installed asciidoc plugin on your editor). You can see how easy it is to generate documents in the format you want from IntelliJ.
The following diagram summarizes the different parts of this approach.
Conclusion
Treating documentation as code can improve the quality and consistency of documentation, reduce documentation maintenance overhead, and make it easier for architects and developers to collaborate on documentation changes. And you can even automatically generate documentation as part of your CI/CD pipeline, ensuring that it is always up-to-date and consistent with the application you are building.
Examples in this post are available over GitHub.