As developers, we typically work in keyboard-and-mouse mode. We sit at a workstation or laptop and switch between typing code into a text editor and reading code on the screen.

Diagramming is a less common activity that we may not think about as much. But diagramming can be very useful, both at an individual and a group level, for understanding, facilitating communication, and synthesizing ideas — especially the kinds of ideas that developers often deal with when solving complex problems.

In this article, I will cover: key uses of diagramming, the common diagramming mediums and their advantages, and tips for improving your practice of diagramming, based on my own experience and observations.

Uses of diagramming

Three common uses of diagramming are:

• Understanding a problem/solution
• Helping a group communicate
• Synthesizing ideas

Let me briefly summarize each use before delving into the tips and tricks.

Understanding a problem/solution

The act of diagramming can help with understanding and dealing with a complex problem, by changing how it is represented. From my own experience, I would rank drawing a diagram alongside taking a short break, taking a walk, or consuming a small snack or drink as an effective way to unblock an overwhelmed mind.

By doing something different than usual, your mind gets a break in focus and can recover some energy.

This kind of mental unblocking is especially needed when trying to solve a difficult problem, in which the mind gets into a kind of rut or loop. I find this especially true of code.

When the problem is only represented in code, the mind gets locked into that one representation of the problem and can't get out. By taking that problem and representing it in different medium, like a diagram, the mind gets to re-think the problem afresh.

Helping a group communicate

Diagramming is also a great way to encourage and facilitate communication between a pair or a group of people.

I find this is particularly true in a physical sense. A laptop or desktop workstation often just isn't physically conducive to sharing between more than one person.

The personal computer is clearly designed for a single user. The keyboard, pointing device, and screen are all aligned in one column, intended for one primary line-of-sight.

Even with just two or more people looking at the same screen, there will inevitably be some hunching and huddling, which isn't comfortable, let alone ergonomic, for most people. This 'hunch factor' can apply even more so to hand-held devices, such as phones and tablets.

A diagram — especially a physical one — can make it much easier for multiple people to collaborate around. A piece of paper can be swiftly passed between two people sitting beside each other at a bench.

Multiple people can sit around a table, drawing on their own sheets, without an intrusive screen blocking them from seeing each other's face and hand gestures. People can stand around a whiteboard, each holding a marker, take turns moving in to draw something, then moving out to survey the total drawing.

With everybody feeling a bit more physically comfortable and having a space to contribute and engage, the mental juices are more likely to flow and each member's best thoughts can be contributed to the whole.

Synthesizing ideas

Not only can a diagram help share an idea among participants, it can also help those participants to contribute to, develop, and evolve the idea itself.

A diagram, if drawn a certain way, can have lots of empty white space. This white space can create, in the minds of each participant, a space for contribution. When a participant thinks of something that they want to contribute, they can jump in and draw a representation of that thing in one of the empty patches of space.

And they can connect it to other parts of the diagram, thus building upon the existing conceptual structure of the diagram but adding a new feature or subtly altering its direction. This kind of open-ended synthesis can be the soil of groundbreaking new ideas.

Mediums

Some common diagramming mediums I've observed are:

1. Pen/pencil and paper
2. Virtual pen and paper (e.g. iPad or Surface with stylus)
3. Whiteboard
4. Mouse/keyboard-controlled software
5. Generated (from code)

Pen/pencil and paper

This is the most common medium. Writing implements are typically cheap and easy to get hold of, as are various kinds of writing material, from A4 sheets to pages in a notebook.

Pen/pencil and paper has many advantages.

• It is cheap, widely available, and easy for most people to work with.

• It is very direct. The user can coordinate thinking with hand-movements in a very synchronized way.

• Somewhat related to the above, it is also physical and tactile in a way that the other mediums aren't. The physical act of drawing or writing can, for some people, help to achieve a state of cognitive 'flow'.

• It is highly flexible. The pen/pencil can draw practically anything in two dimensions, without being constrained by, say, a character-set, as with a text file. It can even combine different stroke thicknesses and colors. The piece of paper can be passed around, glued to another piece, be cut into pieces, or posted somewhere. It can be photographed by a phone or camera and readily converted into a digital asset.

Virtual pen and paper

This medium uses the metaphor, and many physical characteristics, of pen/pencil and paper, but in digital and virtual form. Typically it takes the form of a hand-held tablet and stylus, such as the iPad Pro.

This medium shares some of the advantages of pen/paper, though it also lacks some.

• It is much more expensive than pen/paper, both in terms of the machines and energy.

• It has practically the same directness as pen/pencil, at least on most modern devices, where there isn't, say, latency between dragging the drawing device and seeing an appropriate mark made on the digital surface.

• It is slightly less tactile than pen/pencil.

• It is also flexible, but slightly less so than pen/pencil. You can't just, say, glue a tablet to a board or cut it in half. However, if you have a printer handy, you can convert a digital drawing into a paper form, which then has all of those aformentioned flexibilities.

• Marks can easily be wiped out and re-written, making it very fast and flexible for rapidly iterating and evolving a diagram.

Whiteboard

This medium is common in offices, universities, etc. It's great for any kind of team diagramming.

This medium has some unique advantages:

• The large size and upright orientation makes it easy for a group larger than two people to collaborate, jumping in and out as needed to make marks.

• As with the virtual pen and paper, marks are easily wiped out and rewritten, making it very fast and flexible for rapidly iterating and evolving a diagram.

Mouse/keyboard-controlled software

In this medium, we use a desktop or mobile application to construct a diagram. This usually involves drag-drop interactions with a mouse/trackpad. Secondarily, there are usually some keyboard shortcuts for performing common actions (e.g. deleting an element).

Here are some of the most common apps I've seen used for this:

There are some distinctive advantages to this medium, as opposed to the previous

• Importing digital assets. For example, you can locate an image on the web, copy/paste it into a diagram, and then further manipulate it (resize, crop, etc).

Generated from code

This medium is somewhat similar to the previous one, except that instead of using mouse/trackpad to construct the diagram, we write code using the keyboard, and then have the software convert that code into a diagram.

Here are some of the most common apps I've seen used for this:

Methods and tips

Here are some tips I've found useful over the years.

• Pause for a moment before drawing. Think about what you're trying to represent. You don't want to get into analysis-paralysis, of course. But, think of at least the first three elements you might want to draw. Having these in mind will help you to start off with clear, distinct entities, making your diagram more readable and visually pleasing.

• Start drawing at the center and work outwards. By clustering the first few elements around the middle of the page or surface, you leave space to extend the diagram in any direction (up, down, left, right). Most of the time you probably don't know ahead of time what elements will need to be added and where they'll be connected, so it makes sense to free up space to draw them anywhere.

• Use straight, right-angled lines. This may be somewhat a personal preference, but I find diagrams that consistently use right-angled lines to be easier to follow. If the lines are all following that rule, the diagram looks "cleaner," is less noisy, and it's easier to focus on the content. You may prefer a different shape for your lines, but being consistent will probably help with readability, in most cases.

• Leave lots of whitespace. If you leave fairly big gaps between elements, then it's easier to fill in new elements or cross-out elements and add replacements. This is especially handy if a group of people are working on the same diagram, as different individuals might want to add different elements.

• Write clearly, simply and legibly. I've never quite understood why some people rush so much when labelling their diagrams. It's not a speed competition. Take a couple of extra seconds to write clearly and legibly, using big, wide characters that are easy for the eye to follow.

• Learn to draw simple glyphs or icons. A diagram can be hugely enhanced by including a simple visual representation of an object. An actor model could be represented by stick figures for the actors, envelopes for the messages, and 3D rectangular blocks for state. Reactive systems are famously represented as "marble diagrams," with horizontal lines representing time and marbles representing items emitted. For inspiration, try searching [DuckDuckGo Images](https://duckduckgo.com/?q=birds&atb=v105-7_g&t=hf&iax=images&finding a nice picture, and copying it down on a sheet of paper.

• Consider using multiple pen colors rather than just black. For example, if a small group are collaborating on a diagram, each person could have their own color pen so it's easy to keep track of who added what. Or if a diagram conveys multiple layers of information, each color could represent one layer. For example, one color for data, another for code.

• Practice makes perfect. Draw diagrams repeatedly, gradually incorporating the tips above, and watch your diagramming skills improve over time. You want to try some simple repetitive exercises that help you draw cleaner, more symetrically, and with more confidence. See the book Fundamentals of Graphic Language, listed under Further Reading.

When to diagram

Here are some occasions diagramming is particularly good for.

• At the beginning of a task, before coding. Map out the problem and work out the key components of the solution and how they connect.
• When an obstacle arises. You notice you're getting stuck on something. The problem or solution seems to grow in complexity every time you think about it. Time to get everything down on paper!
• When people need to collaborate. Any time multiple people need to get together to work something out, whether it's a multidisciplinary team kicking ideas around, developers building an API that many others will use, or multiple teams co-designing one thing.

Further reading

• Fundamentals of Graphic Language by David Sibbet
• Modelling with UML by Bernhard Rumpe
• The Unified Modelling Language User Guide by Grady Booch