Diagramming In the Real World

TL;DR: Any designer worth their salt should consider being adept at diagramming. However,  we usually see long documents , many verbose emails and chat sessions trying to explain and finalize the design over several meetings. The result might be the same in the end, but the thought transfer takes that much longer. Here we talk about diagramming techniques that I find effective and ultimately help in more eloquent team communication. 

A diagram is worth ten meetings!

My favorite interviews and the ones I always pick to do myself are the design interviews. Simple problems can have such wicked twists. The engineers over the years who’ve done well in those have always had one thing in common - they knew how to diagram. It’s educational to see how an engineer thinks. To have longevity in this business, in my opinion, you got to be a good designer. Great code has great structure and that starts with great design. 

In my teams I’ve always encouraged my teams to use and communicate via diagrams as far as possible, it really helps speed things up. The ironic thing is that anybody with a formal engineering background has learnt these techniques in school, we’re just poor at applying what we were taught I suppose.

Here are a few of my favorite things (diagrams) : 

State Diagrams

I love state diagrams. They’re a great tool to refine your business logic and can answer so many pesky questions back and forth about whether it’s possible to enter this state or that state, or whether something is a legitimate business use-case. It’s so much easier to fall back to a state diagram and apply the transitions and see how the data and objects morph. It’s especially powerful when you start to code as well and need to model behavior. Clarity about your states and transitions will make for robust code design.  

Flowcharts

The bread and butter of our industry. Un-glamorous, but does the job. This is the one technique that I see get used quite a bit. It helps to fall back and remember your flow-chart shapes, because ever so often the flow-chart is going to get really long and you might feel yourself questioning why you’re using that technique. It helps to iteratively design using flow-charts, rather than try and digest one giant flow-chart. Invaluable during a complex code review or performance tuning exercises as well.

Couple with swim lanes when you’re making complex business process flows that encompass multiple functions. 

Block Diagrams

What good designer can get away without drawing really good block diagrams. Deceptively simple (just blocks innit?), but drop that into a system level design discussion and your team will get on the same page really nicely. Block diagrams have been very useful when building complex cross system integrations.

Some of the best system designers I’ve had the chance to work with simply *think* in block diagrams. The whole room is discussing a complex scenario with crazy data flows, and she gets up and draws it all out on the white board in neat little system blocks with in / out’s - instantly settles the room and helps the conversation move forward. 

Sequence Diagrams / Interaction Diagrams

These are the diagrams I’ve used most recently and most effectively. Anybody who has designed an API should be intimately familiar with these. Define your actors and model a classical request / response paradigm. So much nicer than long Wiki pages or Docs that say what has to happen, give me a visual any day! 

Help me, Help YOU!

One of the big blockers that most people have with diagramming is that they’d rather just write out long emails than deal with the intricacies of Word /  Powerpoint / Google Doc diagramming tools. Agreed, things can be painful. Here are a few tools that I use myself to quickly whip up diagrams and document them. 

1. Classic Pen / Paper / Whiteboards : KISS. Take a picture later to document it. I use Microsoft Office Lens, does a super job of converting white boards to PDF’s. 
2. Gliffy : If you use a Wiki, chances are it’s got Gliffy. You can add it on to your Google cloud account as well. Nifty tool, can accomplish most drawings with a minor learning curve. 
3. https://www.websequencediagrams.com/ : My absolute favorite. Hate drawing, no problems. Just write your sequence diagram and out comes an awesome diagram. Not to mention you’re writing pseudo-code as you go. Simply brilliant! 

The Big Picture

Team communication is very critical. Mis-communications can be costly and this is potentially measurable when you detect it eventually. I’ve always stressed on the importance of planning, this critical piece often gets skipped or truncated because you’re having so many other meetings. Using diagrams to communicate and share ideas helps to save a lot of time in meetings and reduces the risk of miscommunication. It’s an indirect cost your team is incurring right now.

That diagram that you think will take forever to make - it’s significantly faster than those five meetings you will have telling your junior engineers what to build. There is something to be said about actually using what you learnt in school, especially when it can be so effective in your toolkit!