Pattern : UNDERSTOOD
NOTATIONS
- CONTEXT : You are writing a pattern and are trying to
communicate concepts that are most appropriately communicated using
diagrams or illustrations. You have identified a Clear Target
Audience.
- PROBLEM : How do you ensure that the diagrams are easily understood by your entire target audience?
- FORCES :
- Diagrams and
illustrations are often more effective than prose when
it comes to communicating concepts, especially those
related to software design. "A picture is worth a
thousand words."
- For any given
concept (e.g. object model relationships) there may be a
variety of diagramming notations and styles that can be
used (e.g. Booch, OMT, etc.).
- Readers are not
necessarily familiar with all such notations and styles.
If the readers are not familiar with the notation you
have used, they may be unable to understand your
pattern. "A picture you can't understand is worth a
thousand words you can't understand."
- Readers are
diverse. If you leave room for interpretation, different
readers may interpret your diagram in different ways.
- Providing a
detailed description of diagramming notations to your
pattern will make it too large, and will distract the
reader from what you are trying to communicate.
- An expressive but
obscure notation is less effective at communicating with
most audiences than a less expressive but better-known
notation.
- SOLUTION :Use diagramming notations that are likely to be familiar to the target audience. Such notations should be
widely used and
easily understood (e.g. message sequence charts). If you are using a standard notation, always provide a reference to the standard. If not, or if
there is any likelihood that potential readers are not familiar with the notation you are using, provide a clear, concise explanation of the
notation when you first use it or refer the reader to a more detailed explanation in an appendix.
- RATIONALE : The more widely used the notation you use, the more likely that readers will be able to understand your
diagrams without the need for a bulky and distracting explanation.
-
RELATED PATTERNS:If the explanation is included within the pattern or pattern language, ensure that it is a Skippable Section.
