Note: This pattern was presented at a workshop at ChiliPLoP 98 by Gary Warren King.

Name

Technical Documentation Patterns

Context

Any system of more than moderate complexity requires documentation to explain it and place its many pieces in their proper context(s). The ideal form of this documentation varies depending on the needs of its readers.

Author

Gary Warren King - Design Systems - ChiliPLoP 98.

1. User Directed Reading

Problem

Each reader has their own context for understanding and assimilation. They may already understand some parts of a system well yet may need extra help in understanding other parts.

Solution

Allow each user to read the system in their own fashion.

This pattern can be achieved by using Hypertext Linkages to provide connections (or amplifications) to other sections of the system. Text Out of Band can also let readers easily skim over unnecessary detail or return to it at their leisure. The Inverted Triangle makes it easier for readers to stop reading when they wish. Hierarchial Outlines provide global context and broad overviews. Navigation Aids provide extended structure and place each part in the context of the whole. Interface Negotiation and Multiple Paths allow the documentation to change its formatting or presentation in response to the reader's needs.

2. Inverted Triangle

This pattern helps to complete User Directed Reading by structuring text so that the most important information appears first.

Forces

This pattern is not applicable when the entire structure must be understood as a whole (see Hierarchial Outline).

Problem

People often need to see the big picture without delving into the details. Furthermore they may not have time (or desire) to read large chunks of text. However, other readers may want or need to understand at a deeper level.

Solution

Structure the documentation in the form of an inverted triangle: put the most important information first. Then the next most important and so on. The reader can stop at any time when the level of detail exceeds their current needs.

Example

This pattern is seen in newspaper writing (lead paragraph and follow-up), writing for the World Wide Web (cf. Jacob Nielson (www.useit.com)) and (in a different vein) in top-down code design (construct routines out of sub-routines that are defined elsewhere).

3. Hypertext Linkages

This pattern helps complete User Directed Reading by providing useful linkages between different parts of the documentation.

Problem

Complex systems have parts that relate to other parts in complex ways (that's why they're complex). Strictly linear documentation often fails to capture these relationships or does so in an unwieldy fashion (for example, effectively using the Windows API often requires having references to many documents open simultaneously). Readers need ways to navigate among documents quickly and return to their starting points easily.

Solution

Structure documentation with Hypertext Linkages aids that link related information coherently.

Each linked document chunk will have it own internal structure. These may be in the form of Inverted Triangles, Hierarchial Outlines or other forms.

4. Text Out of Band

Alias

Multi-Dimensional Text

This pattern helps to complete User Directed Reading by structuring additional or related (but non-central) information in standard (and comprehensible) formats.

Problem

Some documentation does not flow with the body of the text. It may be overly technical or of interest only to a few readers. Yet this information must be accessible to all readers without diverting from the main thrust of the text.

Solution

Use the traditional writing techniques of footnotes, endnotes, appendixes and sidebars. Appendixes and sidebars tend to work best for larger chunks of technical information. Sidebars are usually smaller than appendixes and often provide examples or brief technical summaries. Footnotes and endnotes are used to provide opinions or brief amplifications of the main text. Footnotes are more accessible (and hence, more distracting) than endnotes. Endnotes can be more frustrating for readers to use.

Out of Band text may be reached via Hypertext Linkages. Flexible systems may be able to use Interface Negotiation to structure the same information in various ways depending on reader preference (e.g., converting endnotes to footnotes or vise versa).

5. Hierarchial Outline

This pattern helps to complete User Directed Reading by providing a broad yet structured view of the system being documented.

Problem

Some information can only be understood as a whole (the parts are not coherent in an of themselves) yet the pieces are too complex to explain in detail all at once.

Solution

Structure the information in a hierarchy or outline form that (ideally) can be expanded and contracted as the reader desires (either on-line or in the reader's mind).

Since all the parts must be viewed as a whole to be understood, Inverted Triangle may not apply.

6. Multiple Paths

This pattern helps to complete User Directed Reading by providing a multiplicity of canonical paths through a document space from which each user can choose.

Problem

Each reader has their own needs for understanding and comprehension yet many of these can be anticipated (at least in broad form). It is tedious to wade through information that is already known or redundant.

Solution

Provide a navigation system (or set of suggested paths) that guides readers through the documentation

This pattern is often seen in textbooks that show, for example, which chapters can be used for various courses or readers. It is used in the Trellix(tm) software package to provide multiple high-level views of a document. Hypertext Linkages can help to create the various navigation paths.

7. Interface Negotiation

This pattern helps to complete User Directed Reading by modifying the documentation to suit a given reader's preferences.

Problem

Each reader has different preferences and needs (some require only high-level overviews, others need to know every tedious detail).

Solution

Structure the documentation and the interface to the documentation flexibly so that it can be modified to suit the reader. For example, allow footnotes to be converted to endnotes (see Text Out of Band) and vise versa and allow outlines to be expanded and contracted as desired (see Hierarchial Outline)

8. Navigation Aids

This pattern helps to compete User Directed Reading by providing readers with an overview of the complete structure of the documentation at local and global scales.

Problem

Complex systems have complex documentation. It is easy to get lost following linkages (see Hypertext Linkages) or to fail to see the forest for the trees.

Solution

Provide as many navigation aids as possible. These may be structured as margin note that provide an outline (see Hierarchial Outline and Text Out of Band) or as extended link information (e.g. visited Hypertext Linkages are red, unvisited linkages are blue). They also include tables of contents (perhaps arranged in an Inverted Triangle, or Hierarchial Outline) indexes, etc.