Pattern : SINGLE PASS READABLE
- PROBLEM : A person in search of a solution may need to
look at many potential solutions. How do you help the reader
understand your pattern in the least amount of time, in order to
facilitate this search?
- CONTEXT : You are writing a pattern with Mandatory Elements Present.
-
FORCES :
- People sometimes only have a limited time to read a pattern.
- People get frustrated and give up when the effort is too high.
- A pattern that must be read several times before being understood is more likely to be
misunderstood.
- A simple message is more likely to be understood correctly.
- SOLUTION : Single-Pass Readable is easier said than done, and probably merits a pattern language on its own. However, here
are a variety of techniques which can be helpful to achieve single-pass readability:
- Use Evocative Pattern Names or Pattern Thumbnails in cases where some understanding of a forward referenced
pattern is necessary for the
reader to keep reading.
- Help the reader locate key information by using Findable Sections and Visible Forces to highlight the
tradeoffs involved.
- Use Skippable Sections (such as Code Samples as Bonus) to highlight information which can be skipped on first
reading.
- In a pattern language, provide a clear, concise Pattern Language Summary outlining the structure of the
pattern language, then remind the
readers where they are within the structure as they go along, using (Distinctive) Headings Convey Structure.
- If you need to introduce and/or define a number of concepts or terms in the introductory sections of your
pattern, try to pare down your
list by selecting only the most essential concepts and terms, and write your pattern using this reduced list. Remember that normal adults
are able to keep seven (plus or minus two) items of information within their short-term memory [Miller56]. If you introduce more
information than your reader can remember, he/she will need to keep referring back to the beginning, which defeats single-pass
readability.
- Provide a Glossary so that readers don't have to search around for definitions of terms which they can't
remember. This isn't Single-Pass
Readable per se, but it is preferable to the alternative.
- RATIONALE : In order to help the reader get what they need from your patterns in the minimum amount of time, you
need to help them to read only the sections they need, only once. Skippable Sections and Findable Sections will help readers to find the
sections they need. The techniques described above help the reader avoid going back (or forward) to read sections more than once.
-
RELATED PATTERNS :
- (Distinctive) Headings Convey Structure
- Skippable Sections and Findable Sections
