Draw Fantastic Diagrams

Great diagrams are not just beautiful pictures. Great diagrams are accurate models that reflect the conceptual underpinnings of the architecture. Architects may be infamous for drawing box and line diagrams, but there’s more going on in these diagrams than just coarse-grained abstractions.

As you learned in ​Show the Architecture from Different Views​, you can show many different design ideas with diagrams. Visualizing the architecture with a diagram makes it tangible in a way that other mediums cannot. Fantastic diagrams make the architecture accessible to everyone.

Here are some tips for creating fantastic diagrams:

Let’s explore these tips in more detail.

Use the Legend, Don’t Just Include a Legend

What do the symbols in this diagram represent?

Without a legend, it is impossible for us to know what’s happening. Here is the same diagram, this time with a legend:

We can see immediately that we’re dealing with fine-grained web services and that the communication mechanism relies on Apache Thrift.^[18] Downstream designers responsible for implementing a component in this architecture will want to know these details. Other stakeholders can use this information as the basis for further conversations.

The legend introduces the architecture’s conceptual meta-model (introduced) to our audience. Draw the legend first and use it to keep our diagrams consistent with reality and turn them into tools for analysis.

Now that we have a common understanding of the meta-model, we start to notice mistakes and have questions about the diagram. Should the Analytics Monitor and Data Scrubber be microservices? What if I told you the Analytics Engine service provided a REST interface and not Thrift? Is this a mistake, gap in knowledge, or plan for the future?

No matter what notation you use, every diagram should have a legend. This advice applies to standardized notations such as the UML as well as custom notations. Not everyone who sees our diagram will be familiar with the dialect of UML you use. Legends enhance meaning.

Simon says:

Keep It Simple and Complete

By Simon Brown, independent consultant and author of Software Architecture for Developers [Bro16]

Having run diagramming workshops for more than 10,000 people around the world, I can say with some confidence that software developers struggle to communicate software architecture using diagrams. Many of the diagrams I see focus on the decomposition of software into logical building blocks, although they usually do this at the expense of information about technology. After all, we’ve been taught to keep the “logical view” of a software system separate from the “development view.” Unfortunately, this tends to result in a collection of diagrams that make little sense when viewed individually, with neither diagram providing an accurate reflection of the code.

One solution is to merge the logical and development views of a software system, treating the combined diagrams as a collection of zoomable maps on top of a code base. This is the concept at the core of my C4 model—a collection of diagrams that show varying levels of abstraction. A System Context diagram shows your software system and how it fits into the environment around it, in terms of users and other software systems. A Container diagram zooms into your system boundary to show how it’s made up of containers (applications and data stores). A Component diagram zooms in to a particular container to show the components inside it. Optionally, a UML class diagram zooms into a particular component to show the code-level elements it’s built from.

Although UML is still useful, I prefer a simple boxes and lines notation to describe software architecture. To avoid confusion, my advice is to keep the notation as simple and self-describing as possible, adding a key/legend where necessary. Finally, adding more text to boxes is a great way to add information about responsibilities, providing a nice, at-a-glance view and removing ambiguity from what is usually just a collection of named boxes.

Highlight the Patterns

The previous diagram is hiding a secret. Look what happens if we move some of the components around. Notice that we only changed the elements’ positions.

Rearranging the services reveals that services in this architecture are allocated using a multi-tier pattern! This rearrangement might seem inconsequential, but making the patterns visible communicates the intent behind the architecture to downstream designers. For example, knowing this is a multi-tier pattern, I would not expect the REST API to communicate directly with a database from the Data Tier.

We want the patterns to be visible in the diagrams we draw. We can accomplish this in a variety of ways. Choose names that reflect the pattern. Create views that highlight the patterns we’ve selected. Arrange the elements so you can see the pattern. Above all, use patterns as part of your vocabulary for sharing designs.

Strive for Consistency and Simplicity

Every drop of ink in our diagrams means something. Color, shape, orientation, font choice, and position convey meaning. Avoid superfluous details to help readers focus on the ideas you want to share. Choose different colors or shapes to highlight different ideas, not simply to make the diagram look pretty.

When sharing ideas, consistency is king. If an idea from the conceptual meta-model is present in two different diagrams, use the same shapes and colors to represent it. Readers will find meaning behind every change in color and font, even if you didn’t mean anything by it.

Likewise, too many details will overwhelm and confuse readers. Sometimes we’ll need multiple arrow heads to express an idea. Other times, too many arrows obfuscate meaning. Work to create the simplest diagrams as possible that still provide meaning.

Provide Descriptive Prose

The stories that accompany the picture are the most interesting part of a view. The story explains how elements in the view come together to promote or inhibit quality attributes and why we designed the system the way we did. Sometimes the diagram is the least interesting part of a view. All the action is in the story!

We’ll use descriptive prose to tell the stories about our architecture. Descriptive prose can be a simple table, paragraphs of text, bullet points, or even a verbal narrative. Think of diagrams as visual aides for stories about the architecture: where the architecture came from, how it works, where it’s going.

In Chapter 11, ​Describe the Architecture​ you will learn how to share the stories that accompany views. Diagrams are a vehicle for communicating design decisions and context, but diagrams can’t speak for themselves. It’s up to you to provide the story.

Joe asks:

Should I Use an Architecture Description Language?

We’re not going to cover formal Architecture Description Languages (ADLs) in this book, but you should be aware that such a thing exists. Most architects use simple drawing tools such as PowerPoint, Visio, and Graphviz for day-to-day work. Some people even use pencil, paper, and a phone camera to great effect.

Simple diagramming tools are easy to use and produce shareable diagrams, but pictures don’t easily facilitate in-depth analysis. ADLs solve this problem by restricting and enforcing the vocabulary used to specify models. ADLs are usually implemented in tools, which can run automated checks against the models. Some ADLs can even generate or reverse-engineer code.

ADLs sound awesome but in practice don’t always make life easier. The ADL you select will limit expressiveness of the design. Software tools that support ADLs will often save models in proprietary formats. In my experience, most tools are immature and have a steep learning curve.

My advice is to use an ADL only if you really, really want to use one. You can peruse an up-to-date list of ADLs at http://www.di.univaq.it/malavolta/al/.

Get Your Hands Dirty: Critique Some Diagrams

Find some diagrams from a recent software system you helped build. Knowing what you know now about how to visualize the architecture, what would you change about these diagrams? If this project is still in progress, try to improve the view and share it with your team.

Here are some things to think about:

• What does the diagram help you to reason about?

• What are the essential patterns in the diagram? Are there hidden patterns?

• What is the underlying meta-model? Can it be discerned from the diagram alone?

• Is the diagram complete? Could it be simplified and still be effective?