Diagrams or documentation?

[freeman3101]

As accomplished modellers we often revel in the beauty of the diagrams
we craft in response to the requirements of our customers. It is so
perfect that we hesitate to add words to it lest it detract from the
wonder of the ageless creations we have wrought.

The abovementioned statement is, of course, made with tongue firmly in
cheek. And yet it is not that far from the truth. Modellers are
generally drawn to the visual description of business and system, and
often fail on properly documenting the text that needs to be added to
make the diagrams clear to everyone.

A while ago I wrote an article that highlighted the necessity of both
visual and textual modelling: http://xpdian.co.za/Visualortextualmodelling.html.

In this article I made the case that both the text and the pictures
are vital to the understanding and acceptance of the audience for
which we model.

With the conclusion in mind that we have to use both words and
diagrams to adequately reflect a requirement, the question that
immediately springs to mind is: What do I document in text if I
already have the diagrams?

The simple answer would be:

* For the model area (domain): An executive summary that describes the
entire model subject. This creates context and allows the reader to
understand the bigger picture. This summary may, or not, include the
problem statement that the model aims to solve.

* Per diagram: a brief overview of the purpose of the diagram and what
is described specifically by the diagram as a whole.

* Per element: a brief description of the element, what its purpose is
and why it is necessary.

* Per relationship: a brief description of what the relationship
represents and what it means.

With the wide variety of diagrams used in the UML, documentation is
not as simple as laid out above. The above-mentioned principles should
help with a first-cut description of your model but there should be
more...

Each UML diagram has its own quirks and meaning, and I will spend more
time on how to document each of the diagrams, and its elements, in a
series of writings you can anticipate here soon.

Happy Modelling!