Diagramming for Developers

DZone 's Guide to

Diagramming for Developers

Typically, a monitor, mouse, and keyboard are the only tools a dev needs. But see why you may want to consider another: the humble diagram.

· Agile Zone ·
Free Resource

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 these key uses of diagraming, the common diagramming mediums and their advantages, and then some 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 summarise 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 or bodily 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 be much easier for multiple people to collaborate around. A piece of paper can be swiftly passed between two people sitting beside eachother at a bench. Or multiple people can sit around a table, drawing on their own sheets, without an intrusive screen blocking them from seeing eachother's face and hand gestures. Or people can stand around a whiteboard, each holding a marker, and 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 the best thinking of each member to be contributed to the whole.

Synthesizing Ideas

Not only can a diagram help share an idea between 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 whitespace. This whitespace 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.


The most four most common diagramming mediums I've observed are:

  • Pen/pencil & paper
  • Virtual pen & paper (e.g. iPad or Surface with stylus)
  • Whiteboard
  • Mouse/keyboard-controlled software
  • Generated (from code)

Pen/Pencil & Paper

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

  • Pen/pencil & paper has many advantages.
  • It is cheap, widely available and easy for most people to work with.
  • It is very direct. The user can co-ordinate thinking with hand-movements in a very synchronised 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 colours. The piece of paper can be passed around between people, glued to another piece or cut into pieces or posted somewhere. It can be photographed by a phone or camera and readily converted into a digital asset.

Virtual Pen & 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 aforementioned flexibilities.


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 & paper, marks are easily wiped out and re-written, 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 two.

  • Conversion to some useful form. For example. yEd and Visio allow you to convert a diagram into another form, such as XML, which can be used to generate actual executable code.
  • Bulk manipulations. For example, quickly selecting a number of items (keyboard modifier + mouse click or using the mouse to drag a rectangle around them) and then performing a bulk operation such as delete. Or duplicating elements by copy/paste.
  • 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:




RX Marbles

Methods and Tips

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

  • Pause for a moment before drawing. And 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 centre 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 follow that rule, the diagram looks "cleaner" or 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 and 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, finding a nice picture and copying it down on a sheet of paper.
  • Consider using multiple pen colours rather than just black. For example, if a small group are collaborating on a diagram, each person could have their own colour pen, so it's easy to keep track of who added what. Or if a diagram conveys multiple layers of information, each colour could represent one layer. For example, one colour 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 to draw cleaner, more symmetrically and with more confidence. See the book Fundamentals of Graphic Language, listed under References.

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.
development ,diagrams ,diagram ,agile ,idea synthesis ,communication

Opinions expressed by DZone contributors are their own.

{{ parent.title || parent.header.title}}

{{ parent.tldr }}

{{ parent.urlSource.name }}