It’s no secret that engineers have a certain “style” for their graphic designs, including technical diagrams

If you work in software engineering or within technology, you might have seen a diagram that looks like this:

You might be the author of such a diagram and see nothing wrong. It’s all there — the services, arrows, some protocol information, etc. You understand it well because you drew it, but your audience, they’re looking at a dozen or so beige boxes within a bird’s nest of tangled arrows. Let’s make your diagrams as clean as your code and turn them into something like this:

Why Graphic Design Matters in Software Design

The age-old saying, “a picture is worth 1000 words,” still rings true today, especially within technical settings. As a software engineer or architect, your role is to effectively communicate a technical solution to other engineers, leadership, customers, etc. The more information you can communicate within a diagram, the less you need to explain it using words.

Instead of writing or saying,

“The browser makes a request to the APIGW, which will then proxy the request to one or more backend services.”

why not just visualize it?

A diagram also illustrates the final solution, including all the components involved, i.e., the “big picture.”

And most importantly, it can give your solution a “perceived quality.” In other words, if it looks good, people will think it’s good, even if it’s a bad idea.

What is Bad Design?

Looking again at the first diagram, the unflattering aspects, i.e., the “bad” parts of the design, are:

• Lack of focus. All elements use default colors, lines, etc.
• Messy lines. Effort is required to follow lines through the diagram.
• No clear relationships. Which components are similar, and which are clearly unique?
• No clear flow. What is the primary flow through the architecture, what’s secondary, etc.?

Creating a Better Diagram

Let’s take this bad design and build it into the end result and uncover more benefits to caring about design and communicating visually in your work.

Alignment and composition

The first step in taking a bad diagram and making it better is to clean up the alignment and composition. Do your best to align elements to each other and remove unnecessary line crossings by “untangling” the diagram.

Here’s what it looks like when you apply these changes to the bigger picture:

Color and meaning

Color is an important aspect of your diagram. It can communicate relationships between components, “Unity,” or signify certain components are unique.

In addition, I always strive to make the box or component of the diagram the same color as the technology or company it represents.

Redis is red, containers are blue. I color my boxes, and so should you.

Here’s what it looks like to apply color to the bigger picture:

Using shapes effectively

Shapes also play a critical aspect, just like color. They can unify or isolate certain components of your design. It’s also important not to degrade your design by introducing mixed styles.

If your design is very “flat,” digging out that old user icon in Viso may seem tempting, but it’s much better if you find one that suits your diagram better.

Here’s how to apply effective shapes to the big picture:

Visual flow, leading the eye

If your diagram is complex and has many interactions, a primary or main flow should always be highlighted. It usually originates at the customer or end user and terminates at what they want, such as the data.

Using bolder, more vivid lines will show the viewers that you want to highlight a primary flow through the solution. Here is an example of a load balancer that balances between a primary and a secondary site:

And this is what it looks like when you apply it to the big picture:

Skeuomorphism in design

(Making it resemble the thing it represents)

Skeuomorphism is a nifty design technique to provide familiarity to a user or viewer. A prime example is when you open the notepad app on an iPhone; it looks like an actual notepad that is familiar to you.

You can convey familiarity within your design by turning boxes into more real-world/conceptual representations.

For example, if it’s a server, make it look like a server. If it’s Kubernetes, well, Kubernetes is a platform developers deploy containers “onto,” so a flat table with squares can help convey that.

Here’s how skeuomorphism looks when applied to the bigger picture:

Constructing your own shapes

Often, you’re working within a very basic application such as PowerPoint, Viso, Gify, etc. These programs may not have what you’re looking for, or if they do, it doesn’t go with your style.

You can easily create your own shapes and icons using just basic shapes.

Representing planned and future state

As time progresses, your solution may change between presentations. You will want to add new components or changes to your diagram, but it’s important to ensure these new items or components, which don’t yet exist, are visually represented well. Here are a few ways of doing that:

• Utilize dotted lines for flow and shape lines to represent things that aren’t built yet.
• Avoid coloring new services the same as existing ones. Use a slightly lighter shade.

Let’s add this new component to our existing solution:

Forcing focus

When you want to force your audience to focus on a specific part of your solutions, you can gray out everything except for your focal point.

This is great when doing a presentation. You show the solution, click on the next slide, and then highlight something very specific so there’s no question of where your attention is. Once done talking about it, you can “turn the color back on” and show a normal diagram going forward.

Annotations and comments

Comments and annotations can provide another layer of detail alongside your visuals. Adding additional, yet subtle, information allows your diagram to do more talking for you. It also allows your audience to dive deeper if they want to or ignore them completely if they don’t need that level of information.

Comments and annotations should not be pure black; it’s better to use a mid-gray or something subtle to not draw too much attention.

Here’s how they can be applied:

Relating Work Efforts to Diagrams

We often take a completed design and create Epics, Features, and Stories from them within some Agile process. As a lead engineer, I like to go further and bring Agile back into the diagrams by circling key parts and tagging them with an Epic, Feature, or Story.

Doing this provides clarity as to what work efforts are related to what part of the solution, and as a lead, I can easily “carve up” a diagram into work for other developers.

More Design Tips

Here are additional design tips for you to incorporate into your diagrams:

Different diagram types I use

Conclusion

I hope you’ve learned some ways to make your next designs stand out when you’re presenting to your colleagues, peers, or leadership.

Design can communicate quality, care to detail, and other positive attributes you will want your software to be associated with before you even pick up the code editor.

Finally, using design to bring the Agile process back into your diagrams allows you to clear up confusion, find gaps in your planning sessions and leave your developers confident in understanding where their work fits within the “big picture.”

Graphic Design for Software Engineers and Architects was originally published in Better Programming on Medium, where people are continuing the conversation by highlighting and responding to this story.