5 Tips for Better Solution Architecture Diagrams

Dan Hughes
January 17, 2022

I have been designing solution architectures and mentoring others on better solution architecture diagrams for decades and have long held my "diagram first" mantra, so at this point, I have seen many excellent solution architecture diagrams. I have also seen many not-so-impressive solution architecture diagrams. I have strong opinions about what diagram notations are best for solution architecture. I will restrain those opinions for this article and instead provide some tips that will help you regardless of your preferred approach.

Woman trying to draw a better solution architecture diagram on whiteboard

#1 Start with the Title

You should start every diagram with the simplest of things: a title. The title is more important than you might think: adding the title first establishes the scope of your diagram. How can you create a clear diagram if you are unclear what you are diagramming? The first step to better solution architecture diagrams is being clear about what you are diagramming.

The title is the airport map "you are here" of your diagram. It helps both you and the viewer get your bearings before you dive in.

Cartoon of "you are here" airport map

I expand "title" to include some foundational information about the diagram.

  • Notation. This lets your audience know what language you are using for the story of your architecture. In a case where you have adopted a standard notation (spoiler alert: that is another tip below), you indicate what notation is being used. If you have not, shame on you, but I still recommend some indicator of what kind of diagram it is, e.g., "Data Flow."
  • Scope. This would be considered the title if you were not adding this additional information that I am recommending. It is the name of your diagram and defines the scope. It should be as few words as possible to correctly capture the scope of the diagram. The scope is usually solution's name in the case of a solution architecture diagram. However, you may be producing multiple diagrams from different perspectives in some cases, so you need to be more descriptive, e.g. "Sales Portal - Customer View."
  • Date. All knowledge benefits from a freshness date! The date will help your audience determine which is the most current if they have multiple versions of your diagram. In addition, it will help someone in the distant future know the age of the information they are viewing.
  • Version. A sequential version number makes it easiest for someone to confirm they have the latest diagram. I typically use a 3-digital approach - [solution version].[diagram publication version].[internal diagram revision].

The title is critical for two primary reasons:

  1. It prompts you with the fundamentals of the diagram you are working on, which helps you stay on target.
  2. It provides your audience with information regarding what they are looking at, making it much easier for them to understand the diagram.

#2 Use The Right Solution Architecture Diagrams

I know. "Use the right diagram" seems like a ridiculous thing to say, but it isn't! Different diagramming notations are better suited for specific types of communication. Some diagram formats more clearly depict flows. Some are best for static connectivity. Others are prettier for Powerpoint usage, but trade-off some accuracy for the good looks (I am looking at you, Conceptual Solution Architecture Diagram).

Woman banging head against wall in frustration

Picking the best diagram format for the information you want to communicate makes a huge difference. Sometimes, when I struggle to depict some aspect of a solution architecture quickly but feel like I am banging my head against the wall, I realize that I am using the wrong diagram. It is easier to create a better solution architecture diagram if you are working with the right notation; it's like banging a nail in with a hammer vs. a screwdriver.

#3 Don't Overload a Single Diagram, Create Multiple Diagrams

While creating more diagrams may seem counter-intuitive, having multiple diagrams, each the "right diagram" to communicate a particular aspect of the solution architecture is simpler and more accessible for your audience. Even when that means they need to look at multiple views. At Wittij Consulting, we have a standard set of solution architecture diagrams we produce for any architecture we are working on:

Each is focused on a different aspect of the architecture. The tip to not overload applies to diagram scoping as well. Sometimes two information flow diagrams are more understandable because there are so many boxes and lines a single diagram starts to get confusing.

#4 Use Standard Notations

Both you and your audience benefit when you select a standard set of notations for solution architecture diagrams.

You benefit because once you master a diagramming notation, you don't spend time thinking about the notation and instead can focus on the architecture you are trying to depict. It is like fluency in a language: before you achieve fluency, substantial effort goes into determining the correct word to communicate a thought. The more fluent you are, the less that is an issue. You can more quickly and correctly communicate what you are thinking to someone else.

Multiple people confused trying to communicate with one another

The same is true for your audience. If you were trying to explain your architecture in german, but your audience did not speak the german language, it would be much slower (and more frustrating for them) for you to teach them german so before they could understand what you were trying to explain. With diagramming it is the same, any energy your audience spends trying to understand your diagram distracts from them understanding your solution architecture.

Suppose every time your audience sees an architecture diagram it looks similar to the prior. In that case, they learn the notation then parsing it becomes intuitive, so they can instead focus on the architecture being presented.

Anything on a solution architecture diagram that does not make your solution architecture clearer becomes the noise that makes it more difficult for your viewer to understand the solution architecture.

I am an advocate of adopting an industry-standard notation. When you do, you benefit from pre-existing knowledge, tools, and skilled people. Not to mention the "trial and error" that has already gone into refining the notation. Clearly it is easier to create better solution architecture diagrams when working with a notation that was designed specifically for that! We primarily use UML.

But even if you prefer to select something else or even bake your own approach, it behooves you to pick anything instead of winging it every time you create a diagram.

#5 Leave It Off!

Robot drawing on a blank flipchart

Anything on a solution architecture diagram that does not make your solution architecture clearer becomes the noise that makes it harder for your viewer to understand the architecture. That is why less is always more. A clear architecture diagram is as much about what you leave off it as what you include on it.

When you are done with your solution architecture diagram, I recommend that you review it and see what could you delete from the page without losing important information about the solution architecture. Trust me, you will find something. If your diagram is not left with a healthy amount of whitespace, you need to either keep deleting or follow the aforementioned advice to create multiple fit-for-purpose diagrams.

Better Solution Architecture Diagrams

Artist painting as a metaphor for an architecture creating a solution architecture diagram.

I have a lot more to say about creating better solution architecture diagrams, but those are all the tips for today! Solution architecture is primarily a facilitation activity, so being able to clearly communicate your design is an essential skill. It is a blend of art and science. Studying tools and techniques can get you part of the way there and lots of practice will get you the rest of the way. If you are on that journey, check out our other articles on diagramming.

Dan is the founder of Wittij Consulting. Prior to founding Wittij, he spent a decade in software development before moving into IT architecture, where he created an Open Group recognized architecture method and led delivery of all services for a company specializing in enterprise and solution architecture for 15 years. He is an energetic, thoughtful leader with an ability to engage and motivate people, and has been called a “force multiplier” for his ability to not only deliver great value, but also increase the value and capability of the people around him. Dan is a strong facilitator, able to understand and resolve complex disagreements with diplomacy. He comprehends and communicates clearly both at the detail level and the boardroom summary level to both business and technical audiences. His knowledge of enterprise techniques and technologies is broad and deep, and includes industry expertise in manufacturing, financial services, banking, health care, insurance, regulatory compliance, and NGOs.
Copyright © 2022 Wittij Inc.
crossmenu linkedin facebook pinterest youtube rss twitter instagram facebook-blank rss-blank linkedin-blank pinterest youtube twitter instagram