Communicate with more Appealing Diagrams

In the world of software, what we do is to come up with virtual models, to deal with computing devices. While we primarily deal with computers through software, we also have to deal with different stakeholders throughout the entire life cycle to collect and agree upon different needs and expectations, starting from the software requirements, the architecture and design through to how we deliver and test software.

So if someone asks me, what is the main challenge we continuously have to face? what I would say is “communication”. Well, at least to say it’s one of the most vital things even if it doesn’t turn out to be the main challenge.

In dealing with this challenge, diagrams play a major role, because of the intuitiveness and abstractions it provides over other means of communications. When someone talks about diagramming in the software field, the first thing comes to anyone’s mind would be the typical UML diagrams, which is not the focus here. Actually, there are arguments on the effectiveness of the UML diagrams and even proposals for more simplified models, especially when it comes to diagramming the Software Architecture. There are simplified and more effective diagramming models being proposed by the gurus in the field. For an example C4 model proposes a set of diagrams to cover the Architecture and Design of a software system in an effective way.

The focus of this post is not on formal diagrams, covering the low-level design aspects of a software system (like UML), but more on high level diagrams, which we tend to use for high-level architecture and design communication. While using these high level diagrams, there are small things which may sound like common sense to anyone when pointed out, but these are easily forgotten or not given the proper care. Ultimately it results in the quality of the targeted communication getting dropped. These are the small things which no stakeholder gets to point out, but only get recorded as bad experience in the unconscious mind. So one way to avoid these, is to make the diagrams more appealing through following some simple guidelines.

How can we make the diagrams appealing? Here are 5 simple but important tips.

1. Color Scheme (Using an appropriate color scheme)

Use of colors in a diagram makes a big difference. To a large extent it dictates whether the diagram is going to be dull and monotonous or an appealing and clear one. Even though the use of too much colors could be a problem, careful use of colors could make the diagram clearer to the viewer differentiating different regions, purposes etc. One could learn about the Color Theory and come up with complementing colors, , or the lazy ones could grab a color scheme from an on-line resources.

2. Lines

Lines could denote different meanings in a diagram. It could be showing boundaries, data flows whereas dashed lines could show temporary or standby functionality etc. The thickness of the lines should go along with the font weights.

3. Alignment

Alignments of objects within a diagram is something that doesn’t catch the eye when it’s done right, but when it’s done wrong it’s becomes obvious that “something is not right”. It’s best to try aligning objects both horizontally and vertically, and even try to layout in grid patterns when it’s applicable. Additionally, the objects should be balanced horizontally and vertically.

4. Whitespace

Good use of whitespace in-between the objects makes the diagram clearer and it could emphasize the relationship of group of objects as well as the separation. White-spaces should also be balanced horizontally and vertically.

5. Go Minimal

Another important factor for a clear diagram is to avoid stuffing too much into a single diagram. Adding more objects, links etc. may seem like adding value to the diagram (more information) but it could actually reduce the value of it by not clearly communicating the need, whereas different but consistent ‘set of diagrams’ would be able to communicate the same information more clearly. Additionally, it’s better to avoid features like shadows, 3d perspectives etc. given by the diagramming tools, because it might be catchy at the first look, but it doesn’t really give much value in terms of communication rather adding clutter.

While the above simple tips make a great difference to a diagram, the golden rule is the consistency. Whether it’s the color, lines, alignment, white-space, or anything else for that matter, we need to be consistent for any diagram to be appealing.

To get an idea of how a diagram could be improved, here’s an example such improvement applying these simple tips (even though I don’t say this is perfect).

MANAGING HIGH LEVEL DIAGRAMS AND CHANGE

One of the key things to show in a diagram are the boundaries of different environments, servers, components etc. However, it is something that is easily overlooked and one of the very common mistakes that everyone makes.

Also one diagram should not mix multiple contexts in it. If it’s a logical diagram, it better to include only the logical components and same goes for different contexts like technology views, deployment views etc.

When considering a high-level diagram, it’s not something that’s going to change drastically, given that it is depicting a solution that’s thought through (futuristic). But it might not have all the bit and pieces at the time of drawing. In these situations, the use of colors (as in grayed out areas within the diagram for an example) or dashed lines could be useful to show certain parts/components/connections are optional or yet to realize.

Since communicating over diagrams is so impactful, some of the misunderstandings get cleared away as soon as you come up with a diagram. If something is not easy to explain to a team or even a client for that matter, both parties are get into the same page quickly once we have a shared diagram to communicate with.

Once I worked with a client who was really picky into small things. He was raising the question “why one connection line had different thickness compared to others, did it mean something?”.

At first I was thinking why this is being asked, there were enough and more important questions around that diagram other than that to ask. But in a split second, I realized how nice it was raised (so that we can correct) rather than it leading to different/wrong understanding to tackle at a later time.

Image Courtesy: Header image from unsplash.com/@andrewtneel