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).

Image 1 : Before
Figure 02: After

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


Chathuranga Wijeratna

Associate Director / Principal Software Architect

Overcome Speech Anxiety, Fear and Speak Up

You’re in a scrum training session. It’s just starting off. The trainer is trying to get everyone to loosen up, so he’s asking a few easy questions. The first one, ‘What is agile?’

You don’t really know the answer but you think ‘it’s cool, he’ll just wait for a couple seconds and then answer his own question’. So you decide to wait him out. Now, waiting him out involves a whole lot of work. Counting the spots on the ceiling, checking to make sure there’s no lint on your shirt and above all else, avoiding eye contact like the plague!

You try this for a bit until you figure out this guy isn’t like the rest, he’s going to get his answer if it’s the last thing he does! So you start thinking of possible answers and finally settle on one you like, amidst all the anxiety and fear. You’re not really sure if it’s the right one but, if all the gods desert you and the trainer decides to ask you for the answer, you gotta have something to say right?

But you’ll be damned if you volunteer to answer. No need to shoot yourself in the foot. So you swallow your answer and keep your mouth tightly shut.

Meanwhile, your scrum trainer is still going around the room looking for an answer (some people just don’t know when to quit, I tell you!). Some of the audience volunteer answers (you roll your eyes thinking ‘suckers!’) and some get called on to give reluctant answers while struggling to find the confidence to speak up.

But none of them give the answer, the trainer is looking for. Apparently they’re ALL WRONG!! (Oh the horror!) Now, you’re secretly congratulating yourself for not answering. (Ha haa putha well done, pat yourself on the back). After all, why give a wrong answer and look stupid in front of 30 people right? I mean, if these other guys couldn’t get it right, what makes you think you’ve got the right answer?

Finally, your trainer gets tired of getting the wrong answer and of all the silent introverts, who simply refuse to let their voice be heard. He gives up and decides to just give the answer himself (you smirk to yourself and think ‘he should’ve done that in the first place. Could’ve saved us all a wasted minute’.).

THEN comes the answer. . .

And after hearing it, you could’ve happily strangled yourself with an extension cord! Because it’s the Same Exact Answer YOU THOUGHT OF! How stupid do you feel now?

Ever had this happen to you? Or something quite similar?

I have. And it’s not a pretty aftermath when you realize, you could’ve answered that question, you could’ve gotten the recognition for giving the right answer. . . you could’ve spoken up. . . !


Those dreaded meetings!

Another place that we fail and fear to speak at, are meetings. Yes, you know what I’m talking about; project meetings, stand-up meetings, retrospective meetings, review meetings – all kinds of meetings. It’s like your voice deserts you and your courage abandons you, when you go in to that meeting room. You actually see your confidence waving bye-bye to you at the door as the fear and the anxiety to speak in public, engulfs you. It’s terrible, it’s pathetic but it is also reality.

Why do we lose our voice in a crowd? Why do we feel shy or reluctant to voice our opinions and then regret it later? Why do we let the introvert in us take over and fail to contribute to meetings?  Why, why, why?

Well for one, we worry that we might say the wrong thing, that we’ll get the words wrong and mess it up. We’re afraid we’ll fail and we’re afraid that people will laugh at us for failing. We worry that people will mock our ideas and think them stupid.

Afraid and worried driven by anxiety.

Did you ever stop to think what would happen if you stopped being afraid of what could go wrong and focused on what could go right? Rainbows will appear, fireworks will go off, violins will start playing. You get the idea, Wonderful Things Will Happen.

Maybe, you would get the recognition for your great idea if you spoke up; maybe you would be the one to get the answer right out of a 100 people; and maybe you would not be kicking yourself later, because you regret not speaking up. Because if you’re not going to speak up and contribute to meetings, forums and all kinds of other groups you are part of, how is the world supposed to know you exist?


Do not underestimate yourself!

It’s important not to let your anxiety and fear of failure stop you from being yourself and speaking your mind. Because in a room full of people, if you have a question, I guarantee you, 10 other people will have the same question. So don’t assume that you’re the only one, don’t assume your question is stupid. Don’t kill your idea before it’s born.

Our speech apprehension, thanks to fear of looking stupid is holding us back. It is denting our confidence in communication. You know this for a fact, even though you pretend you don’t. Well, never fear, acknowledging that you have a problem is the first step to solving it (or so I’ve heard). So, what if you do say the wrong thing?

We’ve seen plenty of people say the wrong thing at meetings but a few days or weeks later, do we remember those incidents? No. But, we do remember the people that gave the right answers and the ideas that lead to brilliant concepts.

So what we need to get through these thick skulls of ours is that, whatever tiny bit of humiliation we feel when we mess up in front of a crowd, is temporary. But what about the appreciation and respect you’ll earn for speaking up? That, people will remember for a long time to come.

So really, how do you get over the anxiety, the fear and speak up? How do we convince our petrified brains to shake off that crippling terror and open our mouths?

Well the first step is to get over yourself! Don’t take it all so seriously! You make a mistake, so what?! Everybody makes mistakes, and I mean everybody.

Life is long, trust me, you won’t get through it 100% mistake free. In the end, we only regret the chances we didn’t take. So like Elsa says so aptly in Frozen, “Let it go, let it gooooo…….”. Let your fears go and take a chance. You’ll be so glad you did.

You know what else holds you back from speaking up? Insecurity and self-doubt.

Stop underestimating yourself so much. You didn’t get to where you are now by sheer accident. Nobody handed it to you on a silver platter. You worked hard, studied night and day. You must have retained something in that brain of yours right?

So what makes you think your ideas are worthless, that the questions you come up with are stupid, that the answers you think of are surely wrong? Trust yourself, trust your abilities and learn not to let your insecurities get in the way of taking a chance.

Now you’re thinking, ‘Yeah yeah, easy for her to spout philosophical ideas, they sound great, but really, where’s the practical advice?’ Coming right up!


Start today. Speak up, shake off the anxiety and build your confidence.

So here’s what you do the next time someone asks the audience a question. Think of an answer, close your eyes, and on the count of 5, raise your hand and start speaking. Just do it. You’ll have plenty of time to think of all those horrible ‘what if I’m wrong’ scenarios later.

In that moment, don’t think of anything else but the question and what you think the answer is. Just open your mouth and start speaking. Add to your answer as you go along and when you think you’ve gotten it all out, said everything you wanted to say, then and only then – shut up.

Try it, go on, I dare you!

Try it once and see what happens. (Oh and for those of you, who are wondering ‘why count to 5 instead of something like 3?’ Well, I thought for those of us, who are a bit more chicken than others, a count of 5 would give us a bit more time to find our long lost courage.)

So the next time your boss asks you to do a presentation, don’t think of excuses not to – just say yes. The next time someone asks you a question don’t try to get imaginary lint off your shirt – answer the man! The next time someone asks for ideas, give yours, no matter how stupid you think it might be. Who knows, it might just become the next big thing!

So Be Fearless and Speak Up.

Do It Now. . .

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


Piyumi Dias

was a Software Engineer