Often as a developer I want to explain something that is either very complicated or very abstract to other people and this is not easy always.

In this situation I might use a diagram but I am not particularly skilled at doing this and I find the whole process incredibly frustrating and time consuming.

I recently discovered a piece of software called Graphviz. It lets you describe what items are in a graph and the relations between those items and then draws the graph for you!

For example you could have a diagram as simple as this:

digraph {
A -> B
}

Which will generate the following:

Could not be simpler right? But how about we try something a little more complex?

digraph { 
graph [ dpi = 55 ];
rankdir="LR";
node[shape=record];
subgraph clusterStore {
label="Call Center";
Jack [label="Jack | \{hair: \"black\", eyes: \"blue\"\}"];
Computer [label="Computer System"];
}
subgraph clusterAws {
label="Amazon AWS";
WebServer
Database [label="Dynamo DB"];
}
Customer -> Jack [label="Phones"];
Jack -> Computer;
Computer -> WebServer [style="dashed", dir=both, label="HTTP"];
WebServer -> Database;
Database -> WebServer;

Computer -> Jack;
}

This yields the following

The downside of this is that you cannot directly control the position of individual elements in the graph, though I suspect that by now you are seeing that this tool can be quite beneficial when creating quick technical drawings.

The best thing about Graphviz is that what you see in the code above is actually a language called DOT and quite well supported by a number of tools. This means that you can output nearly any type of image using the Graphviz tools but also that there is a variety of other implementations, most notably a Javascript port that renders to a <canvas> element and a particularly sexy, but partial port that runs on top of d3.

Currently I have Graphviz implemented inside my BDD test scripts so when they fail you can graphically see the state of the system which caused the error, this makes debugging soooo much easier.

If you want to have a play I have prepared a Javascript demo on JS Bin.

So next time you're stuck explaining something, why not give GraphViz a go...