Pattern : RUNNING EXAMPLES

PROBLEM : How can you make it easier for the reader to put a pattern language into practice?

CONTEXT : You are writing a pattern language that provides step by step instruction on how to do or implement something.

FORCES :

The pattern should be clear and complete so that reader can use it with minimum effort or chance of mistake.

The pattern should be as concise as possible without being too terse for most people to understand.

Many people find abstract descriptions very hard to understand.

Examples are very useful but must not take a lot of effort or prior knowledge to understand.

Any one example may not be ideal for explaining a specific pattern.

When a language contains a significant number of patterns, each pattern must necessarily be more concise than a free-standing pattern if only for reasons of overall pattern language size.

SOLUTION : Try to use a single example in all patterns in the language. Explain it once, possibly in the language introduction. Use it to illustrate how each pattern in the language contributes to the solution. Use additional examples where the Running Example does not illustrate the pattern effectively.

RATIONALE : A single Running Example gives the reader more insight into applying the whole pattern language than a bunch of individual examples. In effect, it is a case study. The reader does not need to invest time and effort into understanding the example for each pattern; they pay this cost only once, when the example is introduced.