Photo by Headway on Unsplash

Writing architecture dossiers with markdown in a git repository to make it an efficient artefact

An architecture dossier is a key documentation to master the conception of a solution. Relying on the same tools than developers, to write it will transform it into a very efficient artefact at the core of an implementation

Coding is in my genes. I just love to code. For 20 years, I have used many code editors from notepad, Atom, Eclipse, Rational Software Architect Designer, Visual Studio Code… I am still amazed how ideas become applications only relying on simple text.

Gaining expertise, I faced the challenge to share my ideas, my conception of the apps, with my peers. I started to write architecture dossiers. Easy! Frameworks, UML, word processors, all the elements are available.

This was the beginning of the nightmare.

Not only, I was passing hours to make diagrams, sometimes with PowerPoint, sometimes with Visio, but I was also desperately trying to make my architecture dossier attractive with fonts choice, colors to reinforce my message.

Thinking that my job was done, came the time of the sharing. Anyone trying to use revision marks on such document rapidly figures out how inefficient it is in this context. Colors everywhere, comments, ambiguity with the version of the document …

At this very moment, you realize that you have produced the ultimate inefficient document. Takes your time, wastes the time of your peers, with a perfectible level of quality, never reflecting accurately the code implemented.

Even more paradoxical, coders have sorted out these problems for a very long time to gain in efficiency, by having the right tools, gathering all the required information at a click of the hand:

• Versatile IDEs allow to manipulate seamlessly information in the same environment (code, configurations…)
• Markup languages allow to structure the information
• SCM allow to master the collaboration among team members.

The missing link was to dispose a publishing language: Markdown.

Relying on Markdown changed the way I was making architecture. I was able to publish my architecture dossiers as assets of the project relying on my developer’s tools.

So many advantages:

• Focus on content: Markdown syntax forces the author to focus more on content than colors.
• A development asset: Architecture dossier is done with the same tools that the implementation so that you have it at a click of your code.
• Collaboration: Have you ever tried to collaborate on a document with revision marks? If so, you will adore to use git to collaborate effectively on this document.
• Everywhere: Publishing on git allow a rapid publication of the content anywhere, anytime in seconds.
• All-in-one: Even diagrams can be scripted with add-ons.

Getting Started

I have formalized a template covering the major elements of conception of an architecture dossier directly in a github repo : Access to the Architecture template on GitHub

Formalizing the architecture? Fork the repo, update the files, add, commit, push. Et voila!

Rather than manipulating a single document, chapters are split in separated files to be produced with agility:

• Glossary: Lists all the terms acronym used across the document. An additional spreadsheet is provided in order to ease the formalization of the different terms and acronyms.
• System Context: Depicts the systems as a whole and establishes all the interactions it has with the external world (Human or systems). A default PlantUML file is provided to sketch the diagram.
• Use Case Model: Allows to finely catch the usage of the system. A default PlantUML file is provided to sketch the diagram.
• Requirements: List of all the non-functional requirements that need to be covered (the “How shall perform the application”).
• Component Model: Blueprint of the main part of the solution. Different types of diagram can be established (Static or dynamic such as a sequence diagram).
• Architecture Overview: This important diagram allows to easily communicate on the architecture of the application.
• Architecture Decisions: This crucial chapter consolidates all the decisions taken with the associated context and justification in order to allow a full traceability.
• Deployment Model: This chapter explains how the architecture will be deployed physically. It can be drastically reduced while using a container approach on Cloud dur to the abstraction of the infrastructure.
• Data Model: This chapter depicts how the data will be organized. It is fairly common to have specific tools in the hands of the data architect that generate automatically this diagram.
• COTS List: The list of all product “off-the-shelf”, commercial or not, that are used in the solution.

Of course, as any method, it shall not be applied with dogmatism. Instead, a customization phase shall be processed to adapt the template to its need (From adding/removing some chapters, to an adaption to align on the artifact from the C4 model by focusing on the Context, the Components, the Container (as deployment artifacts))

Add-ons to facilitate the formalisation of the document

Four additional tools have been formalized to maximize the efficiency:

• Diagrams: Tons of nice graphics processors exist on the market (online, to be installed on your laptop). The one I use, is PlantUML. This tool allows to adopt the same strategy for the diagram: Each diagram is “described” as a text with a very intuitive syntax, and the PlantUML (a simple java app) can generate the diagram (directly on your laptop or within a CICD pipeline)

Diagrams are ‘described’ with a simple syntax

PlantUML diagrams to sketch the System Context Diagram

• Table: Adopting the best tools remains a strong factor of efficiency. No doubt that Excel is a very efficient tool while making tables. In order to facilitate the formalization of the architecture dossier, MS Excel spreadsheets are provided in order to capture the information (for example: The list of Nun functional Requirements) and a specific sheet is included in order to translate it automatically to markdown. This text can then be pasted into the markdown file.

The requirements can be filled as an Excel Table

Helpers in the file produce the markdown

• Publishing: Several git distributions allow to encapsulate markdown files in nice web template. As an example, GitHub Pages allows to select different rendering templates to display the markdown template. It has to be note that some constraints might be induced (such as enabling a public access to the dossier)

• Exporting: Even if I am totally convinced that an architecture dossier shall be shared online and consulted directly from the git repo to ensure to have the freshest information, the “principle of reality” leads to propose an export feature in order to be able to share the document as a Word document (.docx) or a PDF file. Again, several exporting processors are available. I am using pandoc as it allows to apply a customizable word template and export the files with a high level of fidelity.