Killring

Rick Dillon's Weblog

Visualizing Directed Graphs

Text-based formats are useful because they afford version-control, and therefore allow changes to tracked and diffed, even when many are contributing.

When I’m thinking about responsibilities and collaborations within or among systems, I often find myself thinking in terms of some sort of directed graph. Often, it’s a simple model of how data flows through the components of the system. Paper and whiteboards are often the most readily available sources, but when the diagram will evolve and be refined over weeks, I seek a more malleable format.

Graphviz and dot

Graphviz is an intimidatingly capable package with origins in AT&T Research. For directed graphs, Graphviz’s dot language is sufficient and simple enough to learn in a few minutes, despite the somewhat scary documentation page I linked to just now. Here are a couple of examples to get you started:

  digraph {
    "Mail Server" -> "Mail Client"[ label="IMAP" ];
  }

Here, we declare a di-rected graph, and label the two nodes of the graph, as well as the edge connecting them. Of course, you can add as many modes as you want:

  digraph {
    "OfflineIMAP" -> "Mail Server"[ label="reads from" ];
    "OfflineIMAP" -> "Maildir"[ label="writes to"];
    "Mu4e" -> "Maildir"[ label="reads from" ];
    "Emacs" -> "Mu4e"[ label="runs" ];
    "Emacs" -> "smtpmail" [ label="runs" ];
    "smtpmail" -> "Mail Server"[ label="sends to" ];
  }

The code is quick to write, and is easy to modify, even when sub-components move around, since Graphviz’s layout engine takes care of most of the heavy lifting. Naturally, there’s a lot more you can do with the language, but this should get you started in three minutes and cover 80% of your needs when it comes to sharing simple directed graphs.

If you use Emacs and Org mode, it’s worth noting that org-babel has support for dot, which allows embedding of source and resulting images in documents. That’s the exact technique I used to write this post. If this matches your use case, check out the Worg page that covers it in more detail.

So, if you find yourself wanting to sketch out a simple directed graph to embed in source code documentation or to share via email or chat to facilitate a design discussion, consider Graphviz and dot; they are easier to use than I expected, and works perfectly with version control so you can track changes.