I recently completed a major project for a large e-commerce concern. As is ever the case, tight schedules, scant resources, and shifting requirements resulted in doing the docs at the end. The package I'd developed, while nicely OO - and in Perl! -, was pretty complex. After typing numerous pages of HTML I realized the result was such a dry pile of text that no one would bother to read more than the first few pages (or, if they managed to read all of it, they'd have forgotten most of it by the time they finished).

What was needed was a little dose of eye candy, something the reader could look at and immediately say "Aha! I know whats going on here!". It should also tie back directly to the class documents (which I render w/ a javadoc-ish tool), and support annotations.

After pondering my options, I grabbed my copy of UML Distilled and found what I needed: Sequence diagrams. Off to Google for a quick search for UML sequence diagram tools. There were a few of the Java variety, then what to my wondering eyes should appear but a CPAN link: UML::Sequence by philcrow. Straight away I pulled it down and gave it whirl. Pretty nifty. Not only could it reverse engineer Java and Perl code, but it had a handy little pseudocode language for rendering higher level, "extemporaneous" sequences.

Alas,

• it lacked a few of the standard UML notations
• it didn't have any annotation syntax
• it only output SVG, and only in black and white

Like any Perl hacker, I was undaunted, and set about to rectify those issues by adding

• Conditional and iteration notations
• external/async event notation
• Embedded annotations as either hyperlinks to footnotes, or as Javascripted tooltips¹
• Hyperlinks to class and method documents (via HTML areamaps)
• A module to produce a raster image of the result (using GD and GD::Text)
• Some options to add a dash of color to the diagram

The result was just what I needed. I set about drafting all the pseudocode to describe all the complex interactions of all those perl objects...and ultimately reduced that dry pile of text to a nice package of HTML that fairly popped off the page and into the reader's cerebrum. To say the customer was impressed and pleased would be a gross understatement.

Here's a sample of some pseudocode input:

AtHome.Wash Car
    /* the bucket is in the garage */
    Garage.retrieve bucket
    Kitchen.prepare bucket
        Kitchen.pour soap in bucket
        Kitchen.fill bucket
    Garage.get sponge
    Garage.checkDoor
        -> clickDoorOpener
        [ ifDoorClosed ] Garage.open door
    * Driveway.apply soapy water
    ! Driveway.rinse
    Driveway.empty bucket
    Garage.close door
    Garage.replace sponge
    Garage.replace bucket
[download]

which produces this (mouse around it a bit to see some of the effects).

philcrow has graciously accepted my updates, and the result now resides in CPAN. So if you need a quick and easy modelling tool to explain those complex object collaborations, give UML::Sequence a try. Your design doc readers will thank you for it.

1. Based on the excellent wz_tooltip.js by Walter Zorn (careful, there be popups there!). Check out some of his other browser tools; he's got an impressive collection of Javascripts for sprucing up those mundane old web pages!