More WebSequenceDiagrams.com Awesomeness

As I’ve been working with a client which has demanded rigorous sequence diagrams as deliverables for the design phase of the project, I’ve started to use WebSequenceDiagrams.com more and more.

I’ve blogged about it previously, but I’ve only come to truly appreciate it after having to use Visio for a few days before I convinced the client that I could deliver the content faster and in an easier to maintain format (well, text) using WSD.

What Visio Gets Wrong

---

I ran out of connection points. Yes, it’s possible; for a long activation sequence, you can actually run out of connection points. One could argue that this calls for a refactoring of the diagram in the first place, but then I would say that you’ve never tried to actually refactor a Visio diagram…I still find it hard to believe: the activation box ran out of connection points; I wouldn’t have believed it if I didn’t see it myself:

I kept having to resize the page. By default, you can’t really fit much on the page. But as I started to build my sequence up, I found that I had to keep toggling around with the paper size just so that I would have a grid. This was annoying since it also involved then zooming out so that I could select everything and reposition it to the top left corner of the page then zooming back in. You’d think that Visio would be smart enough to do this, but it isn’t…

I kept having to move elements around. Want to add a new step? What about introducing a new actor in between two existing actors? Prepare for some carpal tunnel my friend. There’s simply no easy way to do it aside from zooming out, grabbing everything to the right and shifting it around while counting gridlines and getting your result some 10-20 clicks later. What’s worse is that you end up having to scroll around horizontally (reordering actors) and vertically (reordering steps) while dragging a bunch of stuff around.

I kept having to fix connection lines. This was absolutely mindboggling: if I extended an activation, it would cause the first connection on the activation to jump, which would then require me to manually drag the connection back to where it belonged. I probably spent a good 10% of my time simply fixing these connection points as a adjusted activations:

This is an incomprehensible design flaw; I have no idea how people work around this in Visio since I adjust activations multiple times as I’m working through a diagram.

There was no representation of alternate paths or optional steps. I ended up having to draw a rectangle and manually managing the size of it as I changed steps and added more steps. What made this even more annoying was that having the rectangle, even though I sent it to the back, then made it difficult to select elements that were enclosed by the rectangle like a message line or a connection point or a note; I’d end up selecting this stupid rectangle instead.

I had to keep managing the location of notes. The notes don’t seem to anchor to anything and it’s not clear to me how that’s supposed to work. That meant that I had to keep moving notes around as I changed activations and modified connection points.

The lifelines didn’t synchronize. For the life of me, I couldn’t figure out how to get the lifelines to synchronize in length so I didn’t have to manually go back and drag each one down to the same length. You can’t actually CTRL+click two lifelines, as one would think you’d be able to do, and drag them both to extend them simultaneously. I mean, this seamed like pretty basic stuff to me.

So yeah, all in all, I’m not sure why anyone would want to subject themselves to the pain of creating sequence diagrams in Visio. Maybe if it’s a final product and you don’t plan on touching it ever again and you’ve already done most of the work on paper or something, but it’s a terrible tool if you’re just trying to think an idea out and see it visually.

What WebSequenceDiagrams.com Gets Right

---

I can’t speak to the console program or the DLL (yet), but I decided that the only way that I could do this right was to do it in WSD first and then just use Visio to render the final output. While doing it in the browser is fine, I found it much easier to do it in EditPlus, my text editor of choice.

The first step was to create a syntax and auto-complete file so that it was a little more user-friendly.

Here’s my .stx syntax file:

And my .acp auto-complete file:

What I get from this is:

I know what you’re thinking: Chuck, that looks like code! By golly, it does! And — at least to me — that’s the beauty; all of a sudden, a frustrating, time consuming, mouse-centric activity becomes a keyboard-centric, coding-like activity. Moving objects around becomes a matter of moving lines of text. Reordering actors involves moving your participant declarations around. Notes stay in their context if you add a step since everything gets pushed down. There’s no manual resizing of anything. There’s no fixing connection points. There’s no stupid. It actually makes working with sequence diagrams, beyond just whiteboarding, much more useful and much more productive as it lets you kind of think out the code by actually writing pseudocode.

I highly recommend downloading EditPlus (you can keep using it for free, perpetually, if you’re a cheap bastard or pony up the $20 for such an awesome editor). For me, EditPlus is a perfect pairing for WSD due to the easy to create language syntax/autocomplete files and the handy split-document feature so you can easily reference your participants at the top.

Simply create a new file type and add the .stx and .acp files I defined:

Now the downside of this whole affair is that you have an extra step of having to copy out the text and pasting it into the browser, but even with that extra little bit of annoyance, the time and frustration saved over working with Visio is more than worth it.

The next step, once I get my hands on the command line tool, is to hook it up to the external tools feature of EditPlus for a quick hit. I’m also considering writing an integration for Visual Studio for custom rendering within VS or at least something quick-and-dirty like an add-in.

One additional note is that WSD has an HTML/Javascript API whereby you can render a diagram inline with your HTML by simply using a set of <pre></pre> tags and a reference to a Javascript file.

What’s cool about this is that now you can use the standard CTRL+B/CTRL+E shortcut keys to preview without a copy/paste step! For free! That’s pretty awesome.

Of course, the downside is that using this method, there is a limit to the size of the sequence that you can send up as well as the fact that you need some additional hijinks to make the syntax highlighting work (I gave up on that part :-D) . But if were doing it in the browser to begin with or using notepad and you don’t care for the syntax highlighting, then this is a huge upgrade.

Conclusion: stop using Visio 😀 Now I’m just looking forward to WebERDiagrams.com, WebStateMachineDiagram.com, and….well, you get the idea.

My EditPlus .stx and .acp files for anyone that wants ’em: wsd-files.zip (.52 KB)