Preparing the architecture documentation is one thing. Another equally important thing is to make sure that everyone who will be using it, will understand it. Documentation should be clear but also understandable for all people involved in software development. That’s the general clue of the architecture communication, but let’s go to the details.
Requirements
Let’s start with requirements. What makes an architecture documentation a good one. Obviously there are few factors:
- Correctness – architect shouldn’t allow for the existence of incorrect information in documentation
- Up to date – documentation should be always up-to-date and mirror the current state and agreements,
- Helpfulness – in simple words, documentation should help not disturb
- Easily updatable – as every change in development can lead to unpredicted changes, we should be able to easily change the architecture documentation as well,
- Easy to understand – just use simple, understandable sentences, explain with images and diagrams, always be explicit,
- Location – every involved person should have access and be able to find documentation easily,
- Documentation should also take into account some additional stakeholder’s needs
Documentation and communication
Firstly, I want to mention that the documentation is part of the communication. Another communication channels can be in person, but everything what has been said should complement what has been written or prepared in other commonly understandable way.
Software architecture documentation is a significant source of knowledge for all people involved in the project. Documentation should contain overall structure, architecture decisions and reasons helping others to understand why something have to be done in a specific way.
Documentation and communication of the architecture to all stakeholders is the next significant responsibility of software architects. Communication should be prepared for different target groups, as not only software developers are the recipients. That’s why we should prepare stakeholder-specific documentation. This includes producing documents in different formats, styles, structures, notations etc.
How?
To increase the possibility that everyone understands the documentation, we should keep some standards that everyone understand. To decrease entry threshold and push ourselves into better communication, we can use some templates for architecture documentation. One of the most commonly known template is arc42.
Benefits of using the templates:
- Understandability is improved,
- Lower entry threshold for people new to the project,
- Retrievability for people who know the overall structure to find the desired information easily,
- Allows reusing parts of documentation in other places,
- Easier maintainability
As I mentioned in previous section, in-person communication is crucial not only to communicate software architecture at the end but also during development of software architecture. It’s good practice to discuss certain architecture decisions between several stakeholders. Involvement of other people helps to avoid some false assumptions and biases. Crucial part here is to document everything what have been discussed. The downside of talking is that some parts can be forgotten.
Diagrams
Documentation beside text should contain different diagrams. UML (Unified Modelling Language) provides a standardized way of diagram to describe the behavior and the structure of the system and processes.
To describe static structure of the system we can use class-, package-, component- and composite-structure-diagram.
Dynamic UML diagrams show behavior at runtime. They show sequences, steps, activities, and states of the system or its parts. For this we have sequence diagrams, activity diagrams or state-machine diagrams.
Views
Next super important thing in software architecture communication is showing the solutions from different perspectives. Generally is not only showing but when developing the architecture the architects have to understand what they do from different point of views.
In this part, we should take into account the following views:
- Context view – it should depict the context of systems in a bigger picture of entire organizational architecture with thorough explanation. External interfaces should be described here. Business and technical context should be taken into account.
- Building block view – presenting the static decomposition of the system into building blocks and their relationships. This view is usually organized in a hierarchy of levels, showing more and more details on each next level.
- Runtime view – it helps to understand how the building blocks fulfill their respective tasks at runtime and how they interact with each other at runtime. Communication can be through enumerated list, pseudocode, UML diagrams or other diagrams like flowcharts.
- Deployment view – documentation should explain where and how the system will be executed and what other parts of infrastructure it cooperates with.
Cross-cutting concepts communication
Software architects should be able to adequately document and communicate typical cross-cutting concepts. As the cross-cutting concepts can have a huge impact to the design, software architect have to document everything clearly and explicitly. Sometimes it’s enough to mention in documentation about some cross-cutting solutions, but better would be to use always the template. For instance, we can put the information into following points:
- Purpose,
- Constraints
- Solution strategy
- References and additional resources
- Risks
- Rejected alternatives
Interfaces
The next important part are interfaces that software architects should describe carefully. Thanks to some tools, we can also do this in a structured and commonly known way. Usually for describing the REST interfaces we use openapi and the Swagger Tool. It’s essential here to add the descriptions to the respective APIs to explain some corner cases and the general usage, as the endpoints itself are not always fully clear.
An important thing to mention is that the definition of the interface is not always defined by the provider of the implementation, but it can be defined by the consumer of the interface.
I already wrote more about interfaces here.
Architectural decisions communication
Here I just wanted to mention ADRs (Architecture Decision Records). ADRs are the way to document and communicate the reasons for some decision that an architect made.
The goal is to compare different solutions/alternative for the solution to the problem we have. It’s used mostly for the chosen technologies. Before choosing one, we should compare it with other available and document it.
The bast way to document alternatives is answering the following questions for each alternative:
- What assumptions have you made?
- What are the specific advantages?
- What are the specific disadvantages?
- What compromises or consequences arise from each alternative?
- What are the known or estimated costs of each alternative?
The form of ADR should contain the following parts:
- Title
- Status – proposed, accepted, rejected etc.
- Context – what is the issue we want to solve with this solution.
- Decision – what is the proposed change.
- Consequences – what becomes easier or more difficult because of this change
Summary
In this post I summarized the most important thing that architects have to take info account when documenting the architecture to make the communication the most efficient. I didn’t describe the details of the diagrams because this is so big topic that I could create a separate post for each diagram. At the end of my CPSA exam preparation, I am going to create the architecture of the example system, so the diagrams and other aspects will be there.
Btw, I found nice article. It’s about enterprise architecture diagram so it’s a level higher than software architecture topic, but I think it’s worth to read it. Here is the post.