Seeking UML tips or alternatives

[Andy Wardley]

bloke at perlbloke.com wrote:
> [...] a detailed project plan for the management and also some of the investors. 
 > They want it to include clear diagrams and I've been recommended UML,

Did the management/investors recommend UML?

The reason I ask is that UML diagrams probably won't mean that much to your
average executive.  Which means they either want the diagrams as evidence
that you know what you're doing and have done the proper planning (even
if they're not qualified to interpret them), or what they really want is a
few warm and fluffy system overview diagrams that they can put in powerpoint
presentations to impress other management types.  Something like this (googled
at random):

   http://cryptodrm.engr.uconn.edu/adder/diagram.png
   http://www.walking-productions.com/itj/docs/System_Diagram.gif

Either way, I would start by producing such a diagram showing the general
architecture of the system.  It's a good overview for both you and the suits.
The main purpose is to show the boundaries of different parts of the system
(i.e. break a big problem down into a number of smaller, but well-defined
problems) and to identify what is part of the system and what isn't.

You should then produce an Entity Relationship Model (ERM), even if the
management don't really want or need it.  Wikipedia has enough info to
get you started:

   http://en.wikipedia.org/wiki/Entity-relationship_model

This is also a good intro:

   http://tinyurl.com/yw6f6e

The purpose of creating an ERM is to identify the entities (nouns) in your
system and the relationships (verbs or adjectives) between them.  The entities
will (usually) end up being the tables in your database and/or the object
classes in the system.  It is a relatively simple process to turn an ERM
into a data abstraction layer using your ORM of choice (e.g. DBIx::Class).

An ERM is the most important diagram you need and *possibly* the only one.
Class diagrams are useful to show the inheritance tree of different classes
(if you have such a thing), and sequence diagrams can help if you've got some
complex interaction between different parts of the system that you want to
model.  Use case diagrams might also be required to convince yourself (and
others) that you're all in agreement about what the system should do from the
end-user's perspective.  But apart from that, the rest of UML just isn't worth
the effort. It's a lot of paperwork designed to increase the billable time of
highly paid analysts who can't code.  All IMHO, of course.

   http://en.wikipedia.org/wiki/Class_diagram
   http://en.wikipedia.org/wiki/Sequence_diagram

I'm not sure if plugging one's own business on the list is considered OK or
not, but if you're looking for someone to help with this process, or want
someone to look over the diagrams you produce to sanity check them, then
feel free to email me off list.

Cheers
A