Documentation in Software Architecture
Let’s continue to consider software architecture. After we recognized stakeholders, functional and non-functional requirements, it is time to document the results. That is why, in this article in the series, we consider the principles of working with architectural documentation.
However, before to dive deeper with individual cases, I would first like to note what we consider as architectural documentation. Unfortunately, there are no standards in software architecture that need to be followed when creating documentation, such as, for example, in the architecture of buildings. Also, each company may have its own rules for writing documentation, which you also need to follow. In this article, the architectural documentation is referring to the high-level description of the system, showing its fundamental principles of work. The primary purpose of this documentation is to correlate functional and non-functional requirements.
Article series
- The Path to Becoming a Software Architect
- Stakeholders in Software Architecture
- Types of Software Architects
- Quality attributes in Software Architecture
- Documentation in Software Architecture
- Certificates in Software Architecture
- Books in Software Architecture
- System Design Cheat Sheet
Why do we need software documentation
Before describing how to create architectural documentation properly, we need to understand why it is required.
There are three primary goals for architectural documentation:
- Knowledge sharing. It is suitable for knowledge transfer between people working in different functional areas of the project, as well as for knowledge transfer to new participants.
- Communication. Documentation is the starting point for interaction between different stakeholders. In particular, it helps to share the ideas of the architect to the developers.
- Analyses. Documentation is also a starting point for future architectural reviews of the project.
Of course, the critical question that related not only to architectural documentation but to any documentation in general, it does not matter be it project documentation, developer documentation, etc. — when it is worth starting to create and maintain documentation. There is a short formula to answer this question:
(Cx — Cy) > Cdiff
where
Cx = The cost of the project without documentation,
Cy = The cost of the project with the documentation,
Cdiff = The cost of maintaining documentation.
It is also easy to calculate what documentation you need to create, how often it is required to be updated, and other similar questions, using this formula. It also answers the questions of whether the documentation is necessary for small-size projects, long-term or short-term, and so on.
Moreover, how it can be that a project’s cost without documentation is much higher than a project with documentation? Just imagine that you have a project for 200 developers, lasting five years, with an average period of developer’s work on a project which is equal to 2 years. Without documentation, it is pure chaos, even for doing minor changes. A few tips on how to maintain proper documentation are listed below.
Types of diagrams
Let’s consider what types of architectural schemes and diagrams exist that can be used in the documentation:
- Informal. The most common type of diagrams. May be represented in any form. Often acts as the easiest and fastest way of communication between stakeholders. Among the disadvantages — it is almost the same to understand or to be confused, that why it is required a detailed description of the diagram.
- Semiformal. It is a standard graphical scheme or diagram that has certain rules of creating. Among the disadvantages, it does not provide a complete description of each specific element. Therefore it requires knowledge of the semantics of the specific diagram. Also, additional software is required to create these diagrams. Also, each scheme is usually focused on a single attribute. UML diagrams are semi-formal, as well as certain approaches for creating diagrams, for example, https://c4model.com/ or https://en.wikipedia.org/wiki/4%2B1_architectural_view_model.
- Formal. It is in some form a language for describing architecture. Allows making code generation directly from the created schemes. It is more suitable for hardware system engineering. Among the disadvantages: it requires special software and knowledge, both for writing and understanding. Example: https://en.wikipedia.org/wiki/Architecture_Analysis_%26_Design_Language
Tips for writing documentation
At work, I often have to write documentation or maintain it. Therefore, I developed several basic principles for writing it:
- Avoid repetitions. DRY principle (Don’t Repeat Yourself) works equally well as in programming and in documenting architecture. Create links, but do not write the same thing several times.
- Recognize for whom you are writing. Perhaps the most important rule. Documentation for developers and top management may differ dramatically. Therefore, it is necessary to decide for whom you are doing it, then understand what these people need in your documentation and what answers they try to find.
- Avoid ambiguity. In my practice, one of the most frequent problems with documentation. For example, you came up with a solution that is documented in the form of diagrams. You understand it, you know the context, but the person who read it may not know it, and it confuses him what exactly you had in mind. Therefore, you should always provide context for your diagrams as a description. Also, try to use standard approaches. For example, I really love using C4 (https://c4model.com/) to describe my solutions, due to the fact that this approach allows you first to make a high-level description of the system, and then dive into the details at the level of components, containers, and deployment, and also has reasonably formal criteria for describing each element.
- Maintain relevance. In this case, you should find a compromise between time spent and relevance. Here you can again use the same formula which is described at the very beginning of that article. If maintaining documentation is cheaper for a project than the opposite way, then it is the right thing to do.
- Review documentation. You should periodically review the documentation. So you will most likely find places that have lost relevance and are worth updating. Also, try to share documentation with stakeholders and ask for their opinion. It is especially useful when you are starting to document architecture.
Popular tools for creating diagrams
Let’s consider what you can use for creating diagrams, schemes, except the standard whiteboard:
- MS Visio (https://en.wikipedia.org/wiki/Microsoft_Visio ). It allows you to do almost everything possible. One of the minuses — does not work on Mac OS. Not free.
- Omnigraffle (https://www.omnigroup.com/omnigraffle/ ). It is for Mac OS users. Not free.
- Enterprise Architect (https://sparxsystems.com/products/ea/ ). It is paid, but there is a 30-days trial period.
- My favorite, fast, simple, and online tool is draw.io (https://draw.io ). It supports third-party plugins, ranging from C4 to AWS specific. You can do anything as you wish on any platform. Ideal as a whiteboard tool for creating informal diagrams. Free!
