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 not sufficient to tell all the story about your architecture. You will 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 to make your diagrams clearly convey the solution you are proposing?

  • Start by providing high level diagrams before to dig in the details and illustrate your solution in detailed diagrams.
  • Clearly identify the existing systems from the new system you are building in your diagram by using for example different colors.
  • Create only the relevant diagrams based on your goals and your audience.
  • Instead of trying to provide many details in one diagram provide several diagrams that expose different views.
  • If you are using 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 a value and resist the tentation to build several detailed disparate diagrams that will be harder to keep updated. 
  • The last but not the least, is make sure 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 that illustrate 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 level of details they are expecting in your diagrams.
  • Don’t hesitate to propose new diagrams that your team doesn’t use currently but make sure that 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?

There is no bullet magic answer to this question as you have probably rightly guessed. However, there are some considerations that may help you improve the diagram maintenance process.

The high-level diagrams that reflect your solution such as component diagrams, runtime diagrams, and deployment diagrams usually change less frequently. Therefore, for those kinds of diagrams, updating them manually “can be” an acceptable option.

I have been using for the last years. You can easily build different types of diagrams and in addition, this tool is freely available in web version directly on the site , or you can download and install a local version. It can also be used within Confluence (paid version) and can be integrated with IDEs such as IntelliJ and VS Code IDE through free plugins.

A context diagram created using

The 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.
  • There are more and more tools that enable you to create diagrams as code such as Structurizr and PlantUML that allows you to create multiple diagrams in multiple output formats, from a DSL source file.
A sequence diagram created using PlantUML from a textual description

About the Author

My name is Adel Ghlamallah and I’m an architect and a java developer.

View Articles