A Pattern Language for Pattern Writing

By: G. Meszaros, J. Doble
Published in: PLoPD3
Pages: 529-574
Category: Pattern Writing

Summary: What worked well in patterns or pattern languages reviewed at PLoP '95. The guidelines have been reviewed and updated.

Pattern: Pattern

Pages: 532-533

You're an experienced practitioner, and you've noticed a certain solution to a commonly occurring problem. You would like to share your experience with others. Write the solution using the pattern form. Use Mandatory Elements Present and Optional Elements When Helpful

Pattern: Pattern Language

Pages: 533-534

You're using Pattern to describe a procedure with many steps or a complex solution to a complex problem. Some steps may not apply in some circumstances. There may be alternate solutions to parts of the problem, depending on the circumstances. A single pattern can't handle the complexity. Factor the problem and its solution into a number of related problem-solution pairs. Capture each as a pattern in a collection of patterns or pattern language.

Pattern: Mandatory Elements Present

Pages: 535-537

You're using Pattern. To capture the necessary information, include Name, Context, Problem, Forces, Solution.

Pattern: Optional Elements When Helpful

Pages: 537

You've applied Mandatory Elements Present. To communicate other information, if they make the pattern easier to understand or if they provide better connections to other patterns, include Indications, Resulting Context, Related Patterns, Examples, Code Samples, Rationale, Aliases, Acknowledgements.

Pattern: Visible Forces

Pages: 539

You're using Pattern or Pattern Language and are trying to capture a problem with several solutions. To be sure the reader understands the proper choice for a solution, be sure the forces are highly visible. Name each force and visually set it off.

Pattern: Single-Pass Readable

Pages: 539-541

You're using Mandatory Elements Present and want the reader to understand your pattern in the least amount of time. Strive to make your pattern readable in a single pass. Use Evocative Pattern Name or Pattern Thumbnail for referenced patterns. Use Findable Sections, Visible Forces, Skippable Sections, Pattern Language Summary, and Glossary

Pattern: Skippable Sections

Pages: 541-542

You're using Optional Elements When Helpful and Single-Pass Readable. To make it easy for the reader to get the essence of a pattern while still providing enough information to apply it, identify the Problem, Context, and Solution so that the reader can quickly see if the pattern applies. Put more detailed information in sections that can be skipped.

Pattern: Findable Sections

Pages: 543-544

You're using Skippable Sections. To make it easy to find key elements of the pattern, determine the sections a reader will want to see. Clearly mark the beginning of each of these sections. Use fonts, underlining, headings, graphics--whatever is appropriate for your pattern form.

Pattern: Relationships to Other Patterns

Pages: 544-546

To make your pattern part of a larger collection of patterns, use the Related Patterns section to capture the pattern's relationship to other patterns. The pattern may lead to other patterns, may be set up by other patterns, may specialize a more general pattern, or may generalize a domain-specific pattern. There may be alternate patterns that solve similar problems.

Pattern: Readable References to Patterns

Pages: 546-547

To reference other patterns in your pattern, weave pattern names into the narrative. Augment the pattern name with a reference. You can use Pattern Thumbnail for the reference. Set off the pattern name by highlighting it typographically.

Pattern: Pattern Thumbnail

Pages: 547-549

To reference other patterns to maximize the reader's understanding and minimize the reader's effort, use Evocative Pattern Name. The first time the other pattern is referenced, use a tag or footnote with a brief thumbnail description of the essence of that pattern.

Pattern: Evocative Pattern Name

Pages: 549

To name the pattern to make it easy to remember and reference, choose a name to convey the essence of the solution. Imagine using the name in conversation or referring to the pattern from other patterns. Test the name by having people who are unfamiliar with the pattern guess at the solution based on its name. Use Noun Phrase Name or Meaningful Metaphor Name

Pattern: Noun Phrase Name

Pages: 551-552

You're using Evocative Pattern Name and are struggling to create a name that is easy to remember. Name the pattern after the result it creates.

Pattern: Meaningful Metaphor Name

Pages: 552-554

You're using Evocative Pattern Name, and you're struggling to make the name useful and memorable. Find a meaningful metaphor for the pattern, and name it accordingly. The metaphor should be familiar and easily understood by the target audience.

Pattern: Intent Catalog

Pages: 554-555

To make it easy for other pattern writers to reference your pattern, provide a catalog of intents that you can use in Pattern Thumbnail. An intent should be one or two sentences that describe the essence of the pattern.

Pattern: Clear Target Audience

Pages: 555-556

To be sure your pattern will be read by the intended audience, identify the target audience for the pattern solution. Keep this audience in mind while writing the pattern. Test the pattern with representatives from the target audience.

Pattern: Terminology Tailored to Audience

Pages: 556-557

You're applying Clear Target Audience. Use terminology tailored to the audience to improve understandability. Use terms that a typical member of the audience could understand. Use Glossary for terms that may be unfamiliar.

Pattern: Understood Notations

Pages: 558-559

You're applying Clear Target Audience. To be sure that any diagrams will be understood by your readers, use diagramming notations that are familiar to the target audience. The notation should be widely used and easily understood. If you're following a standard, provide the reference or a detailed explanation in an appendix.

Pattern: Code Samples

Pages: 559-560

You're applying Clear Target Audience. You're writing a solution to a software architecture or design problem. To clarify implementation details, provide one or more code samples, written in a programming language likely to be understood by the target audience.

Pattern: Code Samples as Bonus

Pages: 560-561

You're writing a solution to a software architecture or design problem. To clarify implementation details, regardless of the programming language the target audience knows, be sure the pattern can stand on its own. Communicate essential concepts without code examples. Use Code Samples, but be sure these reinforce the solution and are not essential for understanding.

Pattern: Pattern Language Summary

Pages: 562-563

You're using Pattern Language. To give the reader an overview of the patterns, write a summary that introduces the complex problem and the patterns that solve it.

Pattern: Problem/Solution Summary

Pages: 563-564

You're using Pattern Language Summary. To make it easy for a reader to find useful patterns in your language, in the summary, include a table that summarizes all the patterns, including a brief description of each problem and solution.

Pattern: Common Problems Highlighted

Pages: 564-565

You're using Pattern Language. Several patterns in the language solve the same problem. To help readers choose an alternative solution: (1) Capture the common problem and forces in one place in a Separate Problem Description or Referenced Problem Description, or (2) repeat it for every solution.

Pattern: Running Example

Pages: 565-566

You're using Pattern Language. To help the reader understand the solution the language provides, use a single example in all the patterns in the language. Explain the example once, possibly in the introduction or language summary. Use the running example to illustrate how each pattern contributes to the overall solution. Use additional examples if the running example is not effective.

Pattern: Distinctive Headings Convey Structure

Pages: 567-568

You're using Pattern Language. To help readers understand how individual patterns fit into the language, make individual pattern headings visibly different from all other document headings. Prefix pattern headings with hierarchical section numbers where the numbering parallels the language structure.

Pattern: Glossary

Pages: 568-569

You're using Pattern Language. Some terms may not be familiar to the target audience. To clarify this terminology without interrupting the flow of the language, provide a glossary of terms as part of the pattern language.