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,

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

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!

In reply to $picture eq ('word' x 1000) by renodino

Title:
Use:  <p> text here (a paragraph) </p>
and:  <code> code here </code>
to format your post, it's "PerlMonks-approved HTML":


  • Posts are HTML formatted. Put <p> </p> tags around your paragraphs. Put <code> </code> tags around your code and data!
  • Titles consisting of a single word are discouraged, and in most cases are disallowed outright.
  • Read Where should I post X? if you're not absolutely sure you're posting in the right place.
  • Please read these before you post! —
  • Posts may use any of the Perl Monks Approved HTML tags:
    a, abbr, b, big, blockquote, br, caption, center, col, colgroup, dd, del, details, div, dl, dt, em, font, h1, h2, h3, h4, h5, h6, hr, i, ins, li, ol, p, pre, readmore, small, span, spoiler, strike, strong, sub, summary, sup, table, tbody, td, tfoot, th, thead, tr, tt, u, ul, wbr
  • You may need to use entities for some characters, as follows. (Exception: Within code tags, you can put the characters literally.)
            For:     Use:
    & &amp;
    < &lt;
    > &gt;
    [ &#91;
    ] &#93;
  • Link using PerlMonks shortcuts! What shortcuts can I use for linking?
  • See Writeup Formatting Tips and other pages linked from there for more info.