3.9 Documenting models

One of the great dangers that comes for free when you buy an OO CASE tool is the temptation to produce huge class diagrams documenting every class in a system, along with masses of supplementary pictures. The tools make this easy to do. Such work products will be completely useless a few weeks after they are produced and probably not readable by anyone but the developer who produced them.

Figure 36 Documentation style.

Small diagrams are sometimes useful for illustrating narrative documentation, but remember: only developers speak UML. Don't expect users to be able to interpret them - at least not without help. The text must therefore explicate the information summarized in the diagram. Figure 36 illustrates the style of documentation that we favour. There will also be state and sequence diagrams where these illuminate the text.

A project glossary or dictionary is usually an important component of the documentation. It defines the types and all attributes, operations and invariants associated with them. It could also include coverage of business concepts that are relevant to the domain but which do not show up in the type model. Classes should be assigned keywords to help with finding them automatically. A good syntax for this is: topic = Biology; owner = Smith; etc.

Strictly speaking, all the diagrams are redundant because they could all be generated automatically from the type descriptions (Graham, 1998). However, illustration can be helpful to some readers and help with the precision of one's thinking.