Use mscgen for kickass diagrams in your documentation

One of the traits of a great sysadmin is writing good documentation. Good documentation means all the important stuff isn’t locked away inside your head, which is a Very Good Thing.

Some might say that keeping it to yourself is great for job security, but it’s pretty short-sighted. Writing it down means you can:

  • Delegate tasks to your very own PFY
  • Ask for a holiday every now and then
  • Avoid being hassled while sunning yourself on Kuta Beach because you’re the only one that knows how to fix RunsYourEntireBusiness ’99 when it explodes

On the downside, you open yourself to:

  • A smooth transition when you leave for greener pastures, and your replacement has an easy time settling in and picking up where you left off

We think diagrams are an invaluable part of documentation. They communicate a lot of information quickly, in an easily digestible form. This is especially important in high-stress situations when you need to understand and fix things as soon as possible.

We’re fans of for lots of network diagrams (the Cisco icons are stashed under the More Shapes button), and Graphviz’s DOT syntax for simple embeddable box-and-arrow graphs. Inkscape is good for just about everything else.

We’ve recently found another tool for the toolbox, it’s called mscgen. That name refers to “Message Sequence Charts”, but really it’s good for anything vaguely resembling a dialogue between entities.

A canonical example of this would be a network protocol, but that’s a bit dry so we’ll use something more exciting: a phonecall with Anchor’s famous support staff. 😀

# Just a simple website support call
msc {
    a [label="Customer", textcolour="maroon", arctextcolour="maroon"],
    b [label="Anchor support", textcolour="navy", arctextcolour="navy"];

    a=>b [label="Hello is this Anchor?"];
    a<=b [label="Why yes it is. What can I do for you?"];
    a=>b [label="Got a bit of a problem with ournwebsite, we need PHP-GD installed"];
    ---  [label="*tappity-tap-tap*"];
    a<=b [label="There we are, how's that now?"];
    a=>b [label="Our gallery's working perfectly, thank you!"];
    a<=b [label="No problem at all, glad to help."];
Okay, that's a little anti-climactic, but accurate. :)

Okay, that's a little anti-climactic, but accurate. 🙂

That was simple, how about something with a few extra layers? This one's a more complex support query with a billing question at the end.

# A more complex support call, then a billing query
msc {
    hscale = "2.5";

    a [label="Customer", textcolour="maroon", arctextcolour="maroon"],
    b [label="Sysadmin", textcolour="navy", arctextcolour="navy"],
    c [label="Network admin", textcolour="olive", arctextcolour="olive"],
    d [label="Accounts managern(out to lunch)"],
    e [label="Accounts manager", textcolour="teal", arctextcolour="teal"];

    a=>b [label="Hello, I need an IPsec VPN configured"];
    a<=b [label="No problem, that's a bit outside my scope,nlet me put you through to our network admin"];
    b->c [label="Hey I've got a VPN call for you"];
    b<-c [label="Go for it"];
    ---  [label=" *the call is transferred* "];

    a=>c [label="G'day, I hear you can help me with a VPN setup"];
    a<=c [label="That's right, let's start by..."];
    ---  [label=" *Conversation proceeds, VPNs are configured* "];

    a<=c [label="That looks good now, is there anything else I can help you with?"];
    a=>c [label="If you could put me on to your accounts department that'd be great"];
    a<=c [label="Sure, let me just see if I can find someone for you"];

    c-xd [label="*no answer*"];
    c-xd [label="*no answer*"];
    a<=c [label="Sorry about the wait, Alex is having lunch at the moment, I'll try Casey instead"];

    c->e [label="Yo, Rentatek have a billing question, are you cool to take it?"];
    c<-e [label="Sure, hit me"];
    ---  [label=" *the call is transferred* "];

    a=>e [label="Hi Casey, just got a question about our latest bill, invoice no. 12345 from May"];
    a<=e [label="No problem, I'll just pull that up now..."];
    ---  [label=" *the support call is completed and documented in Anchor's systems for future reference, and everyone is happy* "];
Now we're talking! Note the use of different arrow styles, interaction with multiple people, and use of pretty colours.

Now we're talking! Note the use of different arrow styles, interaction with multiple people, and use of pretty colours.

As you can see, the syntax is absolutely braindead simple. It's easy to read in plain text, much like DOT, and it looks great when rendered into an image. One of the things we love about its simplicity is that it's embeddable. We can put mscgen syntax straight into our Moin wiki and have it rendered inline for us through a plugin. Suddenly the documentation is trivial to update if things change, so it actually gets done instead of being left to rot.

If this sounds good to you, it is! Try out mscgen if you haven't already. If you've been meaning to write more documentation this might be just what you need. All the tools we've mentioned here are great at what they do, so if you've been wishing for decent diagrams, it's all here.

If you're an OSX'er and like a bit more sheen, we can happily recommend OmniGraffle. If you're itching for sequence diagrams but don't want to install mscgen, check out WebSequenceDiagrams.