Level Up Your Design Practices

By Ben Justick

Introduction

As an Architect, I’m always thinking about how to articulate a technical design or architectural change that’s in my head in a way that it can be easily consumed and understood to accelerate engineering efforts. When you’ve been doing this for a long time, the most effective design techniques and practices almost become like second nature. However, I’ve found that less experienced engineers and architects often struggle with articulating their design in a way that others on the team can understand. Typically, the right pieces are there, but they are organized in a way that doesn’t complete the puzzle. In this post, I intend to cover the approach and best practices I use in context to practically every architecture and design assignment. My hope is that you gain a practical guide to design that you can start using on your next assignment that leaves your team impressed with the end result.

Step 1 — Do Your Homework

When you first get a design assignment, there’s a very strong possibility that you are going to want to immediately start drawing up design diagrams or creating design documentation. This is something I’m often guilty of myself, especially if I’m excited about a new product or capability and want to start sharing ideas. However, spending a bit of time up front for some homework to research the problem space and to connect with key people almost always yields a high return on investment. There’s a common approach I like to follow when it comes to doing this homework.

I always start by thinking through the questions that I have about the problem space and writing those down:

• Some questions are typically targeted at gathering a robust understanding of the current state application and/or services that may need to change with a special focus on understanding the key points of integration within a current state application or service context.
• Other questions are based on initial assumptions of what may need to change or be built to solve the problem at hand.

For each question I use different approaches (or a combination of approaches) to get the answer:

• Review existing documentation and code. — Almost every design will involve some changes to, or an articulation of, current state components. Often times, there is design documentation you can reference to get up to speed with the current state, but for more detailed changes, or if there is a lack of documentation, spending some time reviewing code is necessary.
• Find out who the key people are, and determine the questions you need to ask them. — For every IT product, there’s usually an expert that either designed it, wrote the code for it, or at the very least understands how it works. Determining who your key contacts are, and how best to engage with them to get the information you need will be critical to the success of most design efforts.
• Some questions require industry related insight and perspective. — You can start with some industry research on the internet, but ideally there are some key people within your organization that have already spent a bunch of time researching a specific service or technology and might have even gone as far as a proof of concept. Reach out to these resources to ask about the information that they have and if there’s anything conclusive based on their work.

This part of the work leans heavily on developing and maturing soft skills that are prone to being overlooked in tech centric organizations. Learning how to adapt to different communication styles and work with people across the organization takes time and practice, but it’s well worth the investment.

Step 2 — Outline the Context and Problem Statement

One common mistake that I often see inexperienced Engineers or Architects make, is starting off design documentation with a complex design diagram. While a great design diagram is an essential part of almost every design assignment, some context is typically necessary to get the reader to a place where they can make sense of what the diagram is trying to articulate. Leading in with some background context on why you’re working on this design assignment and the problem that intends to be solved helps to guide the reader into your headspace and set up the more detailed design that’s forthcoming. This section should intentionally be kept brief and often times a short bulleted list is the most effective way to introduce all of the key historical context and the general problem statement the reader needs to be aware of.

Step 3 — Clarify the Scope and Assumptions

I know that most of you are eager to get to a diagram, but trust me, spending a bit of time to clarify what’s in vs. out of scope, and/or key assumptions that are part of your design will make for a more concise and focused design diagram. This section should really be intended to draw the boundaries around the things you plan to cover as part of your design vs. the things that were considered as part of thinking through the design, but don’t necessarily need to be depicted because they either aren’t changing or are existing points of integration that are depicted in detail in other diagrams. By incorporating this section, you are further guiding the reader into your headspace and getting them prepared for what they are going to see next. Similar to the Context section, this section should be kept as brief as possible and a bulleted list usually is the most effective technique.

Step 4 — Create a Beautiful Diagram

Think about a major purchase you’ve made recently. You likely visited several manufacturer websites while researching that purchase, and made immediate subconscious judgements about the related quality of the products just based on the underlying aesthetics of each website. Similar subconscious judgements are made within the first few seconds of seeing a new design diagram. A diagram that is ugly and challenging to consume might leave you questioning the accuracy of the information it is attempting to depict, or wondering about the overall quality of the product(s). Subconsciously, an unorganized ugly diagram is going to make you think the solution itself is unorganized and ugly regardless of how good it may actually be. In contrast, beautiful diagrams immediately instill confidence in the accuracy and quality of the design.

Simply put, when it comes to design diagrams, aesthetics matter. Let’s take a moment to review some best practices I’ve collected and used over the years, and then explore how we can apply them to make more beautiful diagrams.

Best Practices

• Borrow from another diagram. — Find a diagram that either you or someone else created that you think is a similar to the diagram you want to create and utilize the symbols, shapes, colors, and spacing from that diagram.
• Use colors and symbols strategically. — Use color to group like and contrasting items in the design, to emphasize a key focus area on the diagram, and/or to highlight changes to an existing system. Too much color can create noise or be a distraction, so spend some time to find the right balance of colors that is pleasing to look at and makes the information easy to consume. Also, always have a legend to explain what the different colors and symbols mean.
• Use numbering to articulate flow/steps or for informational call-outs. — For end-to-end flow diagrams, use numbering to articulate the sequence of end-to-end steps. Numbering may also be helpful in context to other types of diagrams if there’s additional details to expand on in text.
• Use abstraction strategically. — Use abstraction to make the diagram less messy. (As long as it doesn’t remove important information from the diagram.)
• Connection arrows should be used consistently — i.e. — All straight arrows or all curved arrows, but not some combination of both. Also, try not to cross arrows if possible.
• Connection arrows should be labeled to clarify ambiguity — e.g. — An unlabeled connection arrow from an API to a Datastore could mean many different things (create, read, update, delete, or some combination). Use labeling to clarify the intent of the connection as needed.
• Make the alignment and spacing of objects as symmetrical as possible — Symmetry helps to minimize visual distraction and facilitates more rapid consumption of the information depicted.
• Approach your diagram like an artist — This practice is more abstract, but is important to take your diagrams to the next level. Everyone has different stylistic preferences, but experiment with options to create your own visual style that makes your diagrams stand out. Over time you may develop a signature style that others may come to admire and replicate.

Theoretical Example Case Study

I’m going to depict a fairly generic system topology diagram that has UI, API, and Data layers. I created all of these example diagrams using Draw.io. The components on the diagram are also labeled generically to keep the example simple. (i.e. — In real life UIs and APIs would have explicit names/labels.)

A Not So Beautiful Diagram

For this first example, I’ve created a diagram that goes against several of the best practices above just to illustrate how poor aesthetic choices make a diagram very challenging to consume.

My guess is that you’ve come across diagrams that look something like this several times in your career. It’s both challenging to consume and has informational gaps due to poor design choices. For example, this diagram probably has you asking questions like:

• How does the Data Access API interact with the databases depicted? Is it reading, writing, or some combination of both?
• Is there some meaning behind the different colors used for the APIs and UIs?
• The call to Downstream API 1 has a chain of calls to other APIs that then calls off to the same databases that the Data Access API calls. How are these calls different from the calls the Data Access API is making?

A Better Version

The version below uses some of the best practices to make the diagram more consumable.

What are some of the initial instant reactions you have seeing this diagram after reviewing the first example? You likely were able to immediately start consuming the information in the diagram rather than spending the first few moments trying to decipher what the diagram was trying to depict. I’m assuming it also made you feel more confident about the accuracy/quality of the design. A few notes on some of key best practices that were applied:

• Colors, symbols, and connection arrows were applied consistently and a Legend was added.
• The detailed call flow behind Downstream API 1 was abstracted to make the diagram less busy, and a numbered call-out was used to offer a point of departure to those details. Note: This assumes that these details aren’t essential to be depicted in context to this diagram and a more detailed end-to-end diagram for Downstream API 1 is available.
• Some of the connection arrows were labeled to reduce ambiguity around the purpose/intent of the connections.
• Alignment changes were made to make the diagram more symmetrical.

Making it Stand Out

There’s nothing wrong with the updated example above. It follows best practices to optimize readability and consumption, and likely represents a good enough stopping point for sharing the design with or across a few product teams. However, what if your goal is to create a diagram that’s going to be shared at the Enterprise level or to possibly be embedded within a webpage to share outside of your organization. You might want to consider some additional aesthetic enhancements to really make your diagram stand out. The example below highlights a few techniques for stylizing your diagram. Everyone’s personal style is unique, so experiment with what resonates with you and create your own signature style!

A few notes on the techniques that were used to give this diagram more of a hand drawn style:

• A few different hand written font sets were selected and applied. (Draw.io allows you to apply fonts from the Google Fonts Library.)
• “Sketch” styling was selected for some objects and connectors.
• Connectors were switched from “Sharp” to “Rounded”.
• A background object was added to help make the stylistic choices stand out more.

Next Steps & Concluding Thoughts

After articulating your design diagram(s) there’s several potential additional sections that could make sense to add to your design documentation based on context. You may have a need to elaborate on design details in context to the diagram, break down high level features/stories, sizing, and ownership of work based on the diagram, or explore alternatives of design decisions that may need to be made. Regardless of the next steps that apply to your specific design assignment, there are a couple of additional key best practices to apply as you start to wrap up the initial draft of your design documentation:

• Review and revise your design documentation with peers and experts in the problem space to ensure that the design is accurate and easy to understand. Design should be approached as a collaborative process rather than something done in isolation.
• Refine the story you want to tell. — At the end of the day, your design should tell a story. In some cases, it will be the story of why changes need to be made in order to achieve a new business goal or priority, while in other cases it might be a more detailed “how to” manual to help a team deliver some high priority work faster. Revisions to your design documentation should be made with your story and intended audience in mind.

Following this approach takes time and experience to hone, but you should start to see immediate benefits as soon as your next design assignment if you take the time and effort to apply it. I hope this also gives you a better understanding and appreciation for the important aspects of design that go beyond just creating an amazing design diagram, while also providing you with the best practices and techniques you need to create that diagram.

To learn more about technology careers at State Farm, or to join our team visit, https://www.statefarm.com/careers.

Information contained in this article may not be representative of actual use cases. The views expressed in the article are personal views of the author and are not necessarily those of State Farm Mutual Automobile Insurance Company, its subsidiaries and affiliates (collectively “State Farm”). Nothing in the article should be construed as an endorsement by State Farm of any non-State Farm product or service.

<hr /><p>Level Up Your Design Practices was originally published in State Farm Engineering Blog on Medium, where people are continuing the conversation by highlighting and responding to this story.</p>