Last updated on March 4th, 2023 at 03:35 pm
“The goal of a diagram is to convey a clear and shared understanding of the architecture.” — Neal Ford.
Crafting architecture diagrams is a skill that needs to be taken seriously by architects. You probably know the expression that says one picture is worth a thousand words, and this is also true for the diagrams to help you illustrate your architecture. As stated by Neal Ford, “The goal of a diagram is to convey a clear and shared understanding of the architecture”.
Even if the diagrams are important, they are insufficient to tell the whole story about your architecture. You need to provide additional documentation to make your architecture clear and comprehensible to your audience.
How to improve your diagram crafting skills?
Designing architectural diagrams can be challenging and requires a lot of practice to improve this skill. Indeed, creating consistent and meaningful diagrams is usually an iterative process that requires collaboration and insights from your team to produce meaningful diagrams that brings clarity and value.
How do make your diagrams convey the solution you are proposing?
- Start by providing high-level diagrams before digging into the details and illustrating your solution in detailed diagrams.
- Identify the existing systems from the legacy systems you build in your diagram using different colors.
- Create only the relevant diagrams based on your goals and your audience.
- Instead of many details in one diagram, provide several diagrams that expose different views.
- If you use different shapes and colors in your diagram, make sure to have a legend to clarify what they mean.
- It is important to clearly label the arrows and relations in your diagrams to convey their meaning.
- Create only the diagrams that bring value and resist the temptation to build several detailed disparate diagrams that will be harder to keep updated.
- Last but not least is to provide a clear title for each diagram.
What diagrams do you need to create to document your architecture?
The diagrams that you need to create change depending on the project you are working on and your audience. Usually, in any project, you will start by creating diagrams illustrating the components and the boundaries of the system you are building.
To identify the appropriate architectural diagrams to provide:
- Check with your teammates what diagrams they usually create.
- Understand from your audience what details they expect in your diagrams.
- Don’t hesitate to propose new diagrams that your team doesn’t use currently but make sure they are useful and bring some added value.
The following are the main diagrams that I usually create to document my architecture:
- Context diagrams
- Component diagrams
- Deployment diagrams
- Activity diagrams
- Swimlane diagrams
- Sequence diagrams
- Data flow diagrams
- State diagrams
How to keep your diagrams up to date?
As you probably rightly guessed, there is no bullet magic answer to this question. However, some considerations may help you improve the diagram maintenance process.
The high-level diagrams that reflect your solution, such as component, runtime, and deployment diagrams, usually change less frequently. Therefore, updating those kinds of diagrams manually “can be” an acceptable option.
I have been using Draw.io for the last few years. You can easily build different types of diagrams, and in addition, this tool is freely available in the web version directly on the site https://app.diagrams.net/, or you can download and install a local version. It can also be used within Confluence (paid version) and integrated with IDEs such as IntelliJ and VS Code IDE through free plugins.
Things go out of control for diagrams that change frequently, such as diagrams that convey low-level details (E.g., sequence and class diagrams). For these types of diagrams, consider the following options:
- Tools that generate the diagrams from the code (reverse engineering). IntelliJ and Eclipse have several plugins, such as Diagrams (Plugin that comes with IntelliJ Ultimate paid version) and UML Generator, a free IntelliJ plugin.
- More and more tools enable you to create diagrams as code, such as Structurizr and PlantUML, which allows you to create multiple diagrams in multiple output formats from a DSL source file.
