Why are architecture diagrams never up-to-date?

Or why they don't even exist in most cases?

Mar 20, 2024

Architecture diagrams are an interesting topic to discuss when it comes to software engineering. At every company that I have worked for it has always been brought up as a discussion point that either those diagrams were non-existing, were not updated or were not at the “standards” they needed to be.

I initially believed that the lack of quality architectural diagrams was due to the experience of the individual. For less experienced software engineers, creating or updating a diagram might seem like a burden, as they could use that time for coding.

However, after experiencing different organisations, I realised that other factors come into play:

A fast-paced company culture

When a company is always in delivery mode and teams have pressure to deliver, there are certain activities that will be left to be worked on afterwards. Architecture diagrams are one of those software documents which are hard to justify as a business output, so under those fast environments they will probably be descoped (and never completed).

A culture where documentation is not important

Similarly, if a company does not have standards on documentation (they may not see the value on it), architecture diagrams will not exist or will not be kept up-to-date.

The individual software engineering standards

The experience you have built over the years defines your own software engineering standards and how you prefer to organise your ideas and work. In my case, I learned to solve technical problems by thinking before jumping into implementing and got used to drawing high level overview diagrams first, and that process became part of my own standard.

It is hard to automate it

I think this is an area where we will see tons of changes in the near future, especially thanks to the LLMs models. Currently, there are numerous automation tools capable of creating architectural diagrams, but they demand considerable time and effort, which often takes a backseat to product development. In my experience, these tools weren't consistently updated after a few months, leading them to become outdated and redundant.

Lack of general knowledge or high level overview

At large organisations, it is really hard to have context about all the different systems that a company has, so as a software engineer you try to get enough context to work in an area or problem space. This causes a potential lack of understanding of how complex systems work together for many software engineers across an organisation, and at the end no one is capable of drawing a general architecture diagram because no one has all the knowledge. In this case you may end up with different diagrams per every team, but not a global one which can connect them representing the big picture.

Rotation of people

People move across teams and companies, so it is just a matter of time before all software engineers who worked on a feature are no longer maintaining it. Over time, new joiners may start to question older documentation because they will lack the context from when it was built and they may not fully understand all the details that were put into the architectural diagrams, so most likely those will not get up to date accordingly.

Do architecture diagrams matter?

A fair question to ask would be whether it matters to have (and maintain) architecture diagrams.

For years I used to think that any software engineer should put an architecture diagram before they started to work on a feature, and it should be considered a requisite to update any existing diagrams with newer changes.

But then I worked with software engineers who were brilliant with their proposed solutions, they were really good at coding and they did not draw any diagrams at all. It took me years and practice to understand why those diagrams are important, and why it may not matter if they are not up-to-date.

To me, it comes down on answering the simple question:

What are you using architecture diagrams for?

Imagine a situation where you are designing a new feature which will require changes to the current architecture. Writing an architectural diagram in this context will help you explain what you are planning to change in a way that does not cause confusion. The power of writing down your intent is that you are making it harder for readers to make assumptions on the proposed solution. Using an architecture diagram will help everyone understand what you are planning to do.

Does this diagram need to be kept up-to-date? No.

That is because it was used to help the planning and proposed solution with the data that you had available at that particular point in time. Think of it as another tool to help with the design and to be combined with an RFC process.

Now, imagine the following interactions:

The CTO asked how many databases with critical information we have in the company, and if we have backups set up for them, because we have an audit happening soon.
A new Head of Security is asking what services are under PCI scope and wants to review what services have access to it to determine if it requires changes.
The Chief Data Officer wants to know where all our data assets are and if they are compliant with regulators.
A new Senior Software Engineer wants to understand how the services in their squad interacts with others.

To help facilitate all those conversations it will be much easier to have a high level overview of the architecture, which can go granular if required.

Does this diagram need to be kept up-to-date? Yes, regularly.

The key is to give it the right importance it has by communicating broadly why the company needs it. If the architecture diagram will help solve important questions which have to do with compliance, regulators and strategic direction, then it needs to be maintained by the engineering organisation as any other service because it will be used in critical engineering conversations.

There are multiple benefits of having and keeping architecture diagrams up-to-date. A few examples are:

It is easier to onboard new members.
It is easier to discuss new projects, migrations and refactors with a clear architecture.
It will highlight potential problems or opportunities to improve.
It will help drive conversations about strategic decisions.
It will help with communication across teams and departments.

How to build good architecture diagram standards?

Here are some good practises to follow when creating architecture diagrams:

Use Standard Notation:
- Utilise widely accepted symbols and notations for architecture diagrams. Common notations include those from the Unified Modeling Language (UML) and ArchiMate.
Consistent Colour and Shape Coding:
- Maintain consistency in colour and shape coding for different elements in your diagrams. For example, use consistent colours for servers, databases, external systems, etc. This enhances readability and helps viewers quickly understand the nature of each component
Clearly Define Components:
- Clearly define and label each architectural component in the diagram. Use concise and descriptive names for components, avoiding ambiguous or generic terms. Ensure that the purpose and responsibilities of each component are evident.
Hierarchical Structure:
- Organise the diagram in a hierarchical structure. Group related components together and use containers or layers to represent different levels of abstraction. This helps in presenting a clear and organised view of the system architecture. A good structure I like to follow is by using the C4 model .
Directional Arrows:
- Clearly indicate the direction of communication or data flow with arrows. Use arrows to show dependencies, interactions, and the flow of information between components. Clearly define the start and end points of each arrow.
Consistent Font and Text Size:
- Maintain a consistent font style and size throughout the diagram. Ensure that text is legible and uses a font size that is easily readable, even when the diagram is scaled down.
Include Key Information:
- Include essential information such as system boundaries, key technologies, and dependencies. Use annotations or notes to provide additional context or details that may not be evident from the diagram alone.
Version Information:
- Include version information on the diagram to indicate the current state of the architecture. This is particularly important if the diagram is part of version-controlled documentation.
Document Assumptions and Constraints:
- Clearly document any assumptions or constraints that influenced the design decisions represented in the diagram. This helps stakeholders understand the context and limitations of the architecture.
Review and Validate:
- As previously presented, some architecture diagrams need to be maintained up-to-date regularly. Make sure to set up time to review and validate those architecture diagrams with stakeholders to ensure accuracy and relevance.

What tools you can use to build them?

There are many tools and software available to create architecture diagrams. As long as you can achieve the standards described before, experiment with some of the tools first to decide which one you like better.

Here are some recommendations to get started:

Manual drawing
- Miro
- Draw.io (diagrams.net)
- Lucidchart
- Gliffy
Code based
- Mermaid
- PlantUML
- Structurizr
- Nommnoml

Closing thoughts

Software Architecture Diagrams are an important instrument in Software Development design, playing a crucial role in conveying design intentions, establishing clear expectations, and facilitating both tactical and strategic planning prior to initiating any development work.

Crafting and maintaining these diagrams requires time and effort. However, when properly executed, they not only streamline the software development process but also contribute to improve team collaboration, ensure alignment with business objectives, and aid in identifying potential risks or technical debt early in the development cycle.

What is your experience on Architecture Diagrams? Please leave a comment below

Living in Software

Discussion about this post