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.
Adding a C4 Component Diagram to a Markdown document
If the git server does not support visualization, you can first make a png or svg drawing from the plantuml server site and send the relevant drawing to the Git server. Then you can give this drawing as a drawing link in the markdown document. You can use this method in drawings you make with other tools.
Arc 42 Template
Arc 42 is a template for architectural documentation. By properly completing this Arc42 template, you will have the key design decisions for your software architecture and the design in one place. 1 — Introduction and Goals 2 — Constraints 3 — Context and scope 4 — Solution strategy 5 — Building block view 6 — Runtime view 7 — Deployment view 8 — Cros cutting Concepts 9 — Architectural decisions 10 — Quality Attributes 11 — Risks and technical debt
You can access the template for markdown on the Arch42 website. There is a draft on the relevant site as a single file or as a separate file for each section.
You can use both C4 Model and UML diagrams in this template. For example, we can use the C4 scope diagram under Chapter 3, the container diagram and the component diagram in Chapter 5. C4 Dynamic diagram or UML sequence diagram can be used in Chapter 6. C4 or UML notation can be used for the deployment diagram in Chapter 7.
For Chapter 10, we can use the tables prepared for the Architectural Trade-off Analysis Method (ATAM). In this context, you can access and use the markdown table draft I have prepared.
Conclusion
It is recommended to keep the software architecture document prepared in markdown format with Arch 42 template and include the C4 model and UML diagrams in the Git structure with the code. This solution offers a high quality, manageable, version controlled and traceable architectural documentation.
Source: Medium - Huseyin Kutluca
The Tech Platform
Comments