I’ve blogged about Scapple in the past, describing how I’ve been using Scapple to do basic network diagrams. If you are willing to give up some of the fancy features you get with an advanced diagramming tool like Visio or Omnigraffle, Scapple can take you reasonably far.
In preparation for a recent change control, I found myself frustrated by the sheer volume of CLI code I was writing. I’d work on the project at intervals separated by sometimes large chunks of time, and would then forget where I’d left off and what part of the project I’d been working on. I’d stare at commands for 15 minutes each time to re-orient myself, remember where I was, and then proceed.
This code was not overly complicated. The project was mostly lighting up a series of new interfaces and routing peers to interconnect a pair of Juniper MX routers with a Juniper SRX cluster. But since I virtualize and aggregate everything I can to avoid re-doing plumbing in the future (VLANs, routing instances, LACP etc.), the code blocks get longer, and all start to look alike. Wait…what was this VLAN & subinterface for again? Oh, right — the OSPF stub area for the management traffic landing on the global routing table. I remember now. And so on.
Scapple to the rescue. What I did was lay out a physical block diagram of the new routers and SRX cluster they were connecting to. Then, I surrounded this small central diagram with text blocks that contained the code necessary to configure each link to communicate with the other side. Each block was connected with an arrow to the device it would be installed on. This approach provided a visual reference for the code, making it much easier to analyze what was talking to what, validate VLAN numbering, and sanity check IP assignments.
This approach was easier than pounding out one massive wall of text to be plugged into each device during the change window. Instead, each element of the change was broken down step-by-step, making for an easier to follow process. As I applied each block of code, I’d add a new Scapple note that said “APPLIED” and connect it to the code block I’d committed.
There are a few downsides to using this approach.
- Scapple isn’t a great text editor, and it isn’t meant to be. I use Sublime Text 2 for plaintext editing, so I’d go into ST2, create the code block, then paste it into a new note in Scapple. That could be a little tedious if you were going back and forth a lot.
- Scapple does something weird with double quotes. I noticed that when pasting a line from Scapple where there were quotation marks, Scapple had converted them from the traditional quotation mark generated by the keyboard (“) into an “enclosing quote” pair. This conversion rendered the resulting quote characters illegal to Junos. Not a big deal, but it meant I had to go back and re-enter my interface description lines.
- The Scapple diagram can take up a lot of screen real estate. That wasn’t much of a problem when working on the diagram on my 2560×1600 display, but I did a lot more panning around when working from my laptop screen directly.
If using Scapple as a visual aid for complex change management appeals to you, you might be thinking that you could do this exact thing with any diagramming tool. You’re exactly right. You could. I’m an advocate of Scapple because it is a simple, inexpensive tool that does 90% of what I want in the way I want it to. By contrast, Visio might do 100% of what I want, but almost never the way I want it. I enjoy using Scapple enough that I’m willing to put up with its few functional limitations as I stretch it in ways the good folks at Literature & Latte probably didn’t intend.