Pattern : SKIPPABLE SECTIONS
- CONTEXT : You are writing a pattern that is part of a
collection intended to be used as a reference. You have applied
Mandatory Elements Present and Optional Elements When Helpful. You
are striving to make the pattern easily understood and Single-Pass
Readable.
- PROBLEM : How do you make it easy for the reader to get
the essence of a pattern while still providing enough information to
apply it?
- FORCES :
- The information
required to determine whether a pattern is applicable
may be a small subset of the information required to
actually apply the pattern.
- People require
different amounts of information to understand and apply
a pattern.
- People sometimes
only have a limited time to invest in reading a pattern.
- A long-winded
pattern description may cause a reader to skip the
pattern entirely because the expected return does not
justify the investment.
- Separating
information into sections may make a pattern more bulky.
- SOLUTION : Clearly identify the Problem, Context and Solution parts so that the reader can quickly determine whether this
pattern applies to them. Put more detailed information (such as forces or code examples) in clearly identified sections that may be
skipped if a person doesn't want all the detail.
- RATIONALE : When the reader is trying to become familiar with a set of patterns, they often want to "cut to the chase"
quickly. Too much information gets in the way.
- RESULTING CONTEXT :Unless the Skippable Sections are at the end, the reader may need to scan for the beginning of the next
section of interest. Use Findable Sections to make this easier.
- RELATED PATTERNS: The pattern Code Examples as Bonus describes a special case of a Skippable Section. Optional Elements When
Helpful describes when to include a section while Skippable Sections focuses on helping the reader read a pattern efficiently
- EXAMPLES : The "Alexandrian" pattern style uses fonts and *** delimited paragraphs to allow the reader to pick out the
problem and solution sections.
