Solutions Architect Tips: How to Build Your First Architecture Diagram

Last week I ran an experiment.

I had a sticky note on my desk labeled "Architecture Diagrams". Whenever I was in a meeting, if I said I can draw a diagram for that, I wrote a tick mark.

At the end of the week, I had 7 tick marks drawn. 7 diagrams I needed to draw after 5 days of work.

To some, that might seem like a daunting task. But it's my job. My job as a Solutions Architect is to come up with designs and share them with others around my organization. The best and fastest way to make sure my ideas are understood is by drawing a diagram.

I enjoy drawing diagrams. But it wasn't always that way. I remember when I first started drawing them I would just stare at a blank screen wondering how to get started. I'd draw a box then delete it. I'd then draw the same box again and delete it again. It took a while for inspiration to strike.

With everything, practice makes perfect. You start understanding how to convey your ideas a little better and you get some muscle memory for building the different types of architecture diagrams. You might even get inspiration for creating a brand new type of architecture diagram.

Let's talk about some tips to kick start your diagramming career.

Have a Clearly Defined Message

This might sound obvious, but a diagram is much more than a picture. It's not just a bunch of boxes, arrows, and text thrown around haphazardly on a page. It needs to convey a message.

All great diagrams tell a story.

Let's take an analogy of learning how to drive a car. When you were learning how to drive, the instructor would describe the steps necessary to start the car, put it in drive, then pull into traffic. There was context around each step to show you how each one was necessary to proceed to the next.

If the instructor said "this is the steering wheel, this is the transmission, and these are the gas and brake pedals", chances are you would not have learned how to drive. You would have tried to figure it out on your own because driving is much more than knowing what the parts are in a car.

But since the instructor explained how the pieces go together and how you interact with them, you pick up on the underlying message. The message the instructor was conveying was how to safely and properly drive a car. It provides context and a deeper meaning than simply labeling the parts of the vehicle.

The same concept applies when building architecture diagrams. Before you draw your first box on the page, figure out your message. If you don't know what your message is, ask yourself what is the value this diagram is providing?

If you conceptually know the message you want to convey but are having a hard time putting it in words, it might help to either talk out loud and describe what you are about to draw, or writing down an explanation of what you're trying to accomplish. By seeing the written words you will have an easier time building your message.

Start High Level

When your driving instructor got in the car with you the first time, they didn't explain what every button, dial, and handle did in the car. That would be overwhelming and you would have retained nothing.

Instead, they showed you the necessary pieces to get you comfortable with the concept of driving. A person can typically remember up to four things at once, so starting with the basics is key to getting them to follow your train of thought.

As developers, we assume "the more information the better" and try to pack in information in data-dense diagrams. But introducing your audience to something without the knowledge you have leaves your diagram looking like hieroglyphics.

Who is the intended audience of this diagram? Are you pitching your idea to someone who is completely unfamiliar with the domain? Start with the system context diagram of the C4 model.

Is your audience a developer who understands all the technical detail and wants to know the ins and outs of what they need to build? Start a little lower with the component diagram of the C4 model.

Give enough information where it isn't overwhelming. Knowing your audience is a great place to start when deciding on the type of diagram to build.

You don't always have to start at the beginning.

Back to the car analogy, if you were teaching someone to drive a manual transmission, you wouldn't show them the steering wheel, gas pedal, and brake pedal if they already knew how to drive an automatic transmission. You'd start by showing them the clutch and the gearshift.

Two Is Better Than One

Did you ever watch those tv infomercials where they say "but wait, there's more"? You want to be like that guy when it comes to building architecture diagrams.

Your first diagram is setting the stage. It is building up a context and shared understanding with you and your audience.

The next diagram is meant to address anticipated questions. When presenting your diagram to someone, you will likely get a handful of questions that start off "how will it...". This second (or third) diagram is designed to be a visual reference for these questions.

These diagrams will be more detailed than the first. If you're following along on the C4 model, the diagrams should go down a level. Provide a level of detail you didn't offer in your original.

Having companion diagrams make your message significantly more impactful and easier to understand.

Once your audience understands you're idea, they will start asking specifics. The subsequent diagrams are there to help answer the specific questions (and also show you did your homework).

In our car driving analogy, this is where we'd start talking about turn signals, windshield wipers, or filling up with gas. These aren't necessary for making the car move, but you learn pretty quickly that they are needed if you want to learn how to drive.

Prioritize The Message Over Prettiness

Diagrams don't have to be beautiful. They have to relay your story. I've worked with many people who abandoned trying to build diagrams because "they weren't pretty enough".

Just start with a box.

Tell your story. What's the first thing you talk about? Put it in a box.

What is related to that box? Is it something functional or another component or a timeline event? Put THAT in a box and draw a line connecting the two.

The objective of a diagram is to build a shared understanding. It's one of the primary responsibilities as a solutions architect. Your diagrams don't have to be a work of art to get your point across. As long as someone can follow the flow, you've done your job.

Conclusion

It can be tricky to know where to start when building an architecture diagram. But if you remember these three things, you'll start building them like a pro.

1. What is the message you are trying to convey?
2. How familiar is your audience with your message?
3. Where can you provide more information to answer follow up questions?

If you use tools like draw.io or miro, you can get a jump start with their formatted templates. Start with a foundation and tailor it to your needs. Remember, it doesn't have to be pretty to be effective. Focus your effort on putting the high value data points in there.

Building diagrams is one of your strongest tools as a Solutions Architect. The only way to get better is to practice. So go draw some boxes and get comfortable putting your ideas down as pictures. It's a fun way to show your creativity.

Happy coding!