Documenting Software Architecture in Code Repository

Markdown is a standard simple syntax for creating professional-looking documents. It is simpler than HTML and can be managed without a special editor for writing. Git configuration management tool also supports markdown format. In the Git environment, markdown is generally used for simple introduction of the project and build instructions. (readme.md). This article describes how to use the markdown format for architectural documentation, along with templates.


Markdown document


Architectural Documentation with Markdown

Managing the architectural design and design decisions of the software together with the code will provide great convenience for the project. When our design is kept in the configuration management environment together with the code, we can carry out the design change and code change together. When new engineer starts to the project and pulls the code to his computer, he has the opportunity to see the architecture of the system.


Prepare Markdown Document IDE

You can use Visual Studio Code and similar IDE to prepare markdown documents together with your code.(There are markdown editors in the market, but it will be more practical to do it from with the IDE). You can use the “Markdown Preview Enhanced” plugin in Visual Studio Code. With this plugin, you can visually see the markdown document in VS Code (Preview). You can also produce HTML, World or PDF documents using the same tool.


MD Document Preparation with VS Code


UML and C4 Diagrams

You can put UML and C4 diagrams that you have drawn with the Plant UML script language into the Markdown document. This way, you keep the entire design, including the drawing, in one place. UML and C4 diagrams that you put in the Markdown document can be seen as figures in the preview window. (with a plugin called “PlantUML”). In addition, when you export pdf or html, you will be able to see these diagrams as figures. The GIT tool has a feature to visually display the design scripts written in this PlantUML. In this way, it is possible to see the design with Bitbucket (with the appropriate version and configuration). This feature is not yet available on the open source Github site.