A Pattern Language for Pattern Writing A Pattern Language for Pattern WritingBy: 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.
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
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.
Pages: 535-537
You're using Pattern. To capture the necessary information, include Name, Context, Problem, Forces, Solution.
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.
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.
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
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.
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.
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.
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.
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.
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
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.