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 draw.io 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?"];
    ab [label="Got a bit of a problem with our\nwebsite, we need PHP-GD installed"];
    |||;
    ---  [label="*tappity-tap-tap*"];
    |||;
    ab [label="Our gallery's working perfectly, thank you!"];
    a
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 manager\n(out to lunch)"],
    e [label="Accounts manager", textcolour="teal", arctextcolour="teal"];

    a=>b [label="Hello, I need an IPsec VPN configured"];
    ac [label="Hey I've got a VPN call for you"];
    bc [label="G'day, I hear you can help me with a VPN setup"];
    ac [label="If you could put me on to your accounts department that'd be great"];
    ae [label="Yo, Rentatek have a billing question, are you cool to take it?"];
    ce [label="Hi Casey, just got a question about our latest bill, invoice no. 12345 from May"];
    a
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.
The post Use mscgen for kickass diagrams in your documentation appeared first on Anchor Web Hosting Blog.