Organizational Devices
By using the organizational devices described in this section, you can make your content easy to find because you indicate its organization. These devices are especially helpful for readers who need to access information randomly.
You'll find information about table of contents and indexes, overviews, chunking (informative headings and listings), formatting (bindings and dividers, white space, highlighting), and visuals.
Based on Huston, Kathy, and Sherry Southard. "Organization: The Essential Element in Producing Usable Software Manuals." Technical communication 35.3 (1988): 179-88.
Table of Contents and Indexes
By providing a table of contents and an index, you give readers efficient means of retrieving the information contained in a document. Use tables of contents to indicate broad subject areas (general topics) and indexes to help users find both general and specific (subtopics) information.
In addition, a table of contents, traditionally placed at the beginning of a document, acts as an advance organizer and provides an outline so that readers know the content and the order in which the content is presented. An index at the end provides details. Because the index is alphabetized, it allows users to retrieve information more quickly than the table of contents.
By employing both of these organizational devices, you allow for the different approaches that readers will use to find information.
Overviews
In some cases, you will use overviews as plans of development, presenting only outlines of the contents of a section, chapter, or entire document. In other cases, you may expand an overview to contain any of the same elements placed in an introduction, such as subject and purpose, audience, and plan of development.
Appearing at the beginning of units of information, overviews reinforce a deductive mode of presentation (general to specific) and help readers build schemata or frameworks within which to fit the information that follows. Overviews function as advance organizers.
When readers use a document as a reference, chapter overviews enable them to determine quickly the specific information contained in sections of the chapter and the order in which you present it.
Chunking: Informative headings and listings
You can organize information for users by dividing it into manageable chunks, both conceptually and visually. Group information in short blocks, rather than burying the content in long paragraphs and sections. Such grouping, however, should not be an arbitrary procedure; it should be done according to main and subordinate ideas.
If you have a unit of thought (a paragraph) consisting of a main point (one sentence) with two subordinate points (each developed in several sentences), your tendency may be to place all of the information in one unit (one paragraph), even though the paragraph will then cover over half the page. In this case, you should chunk the information in two or three paragraphs in order to make content visually manageable.
Informative headings
You should use headings frequently as an organizational device to isolate chunks of information in separate sections or subsections so that users can easily find the information and not have to read through long sequences of paragraphs that all look the same. [Structural headings don't indicate the topic, rather the type of information. For example, scientific research articles have the headings "introduction," "methods," "results" and "discussion," and "conclusions."]
In addition, you should create informative headings that clearly indicate what information is contained in sections and subsections. If possible, for instructions, use the same syntactic structure for headings, preferably verb forms that indicate the actions users perform. Informative headings that are syntactically parallel function similarly to overviews; they provide consistent frameworks within which users can fit the information that follows.
Furthermore, by adhering to similar formatting patterns for headings that are of the same level of importance, you help the reader discern the hierarchy of a section's content relative to other content in the manual.
Listings
Listings are valuable organizing devices for content containing a series of ideas, whether the ideas are expressed as words, phrases, sentences, or, occasionally, paragraphs. By placing information in listings, you can chunk information in order to indicate hierarchical relationships among ideas. Listings indicate which ideas are of equal importance and which are subordinate to other main ideas.
In addition, because of the way listings are formatted, they organize content visually so that users can easily distinguish items in listings from surrounding text. Thus, listings make the information accessible, enabling users to find it quickly and easily.
Long lists, however, can be overwhelming for users. As much as possible, chunk content into main and subordinate units of information when constructing listings.
Formatting: Bindings and dividers, white space, highlighting
Formatting involves any aspect related to the physical appearance of a document. With certain formatting techniques, you enable users to retrieve information in a manual quickly by indicating organization.
Bindings and dividers
You can choose from many types of bindings, such as loose-leaf, spiral, and perfect. When binding is suitable for the document being prepared, pick a binding suitable for the needs of your users. With loose-leaf binders, users can keep large amounts of content organized, particularly if the document is updated periodically as manuals are. Then they can take out and add sections as necessary. Because spiral bindings allow pages to lie flat, they are good choices if readers need to refer to information in the manual as they use the software.
Computer users, for example, often do not read a manual in a linear fashion, especially as they become more familiar with the software. Dividers can help them quickly locate the information they seek. Commonly used dividers include labeled tabs, colored divider pages, and shaded boxes down the right-hand edge of pages (also called bleeding tabs or bleeding edges).
White space
You indicate organization visually according to how you use white space, the portions of a page of text that do not contain words or visuals. With desktop publishing programs and word-processing software, you can also easily use horizontal and vertical lines to define white space. Be aware of the dangers, though, of using too many lines. Instead of indicating the organization of content, they make the page appear busy.
White space can visually reinforce the organization and logical relationships within documents. First, you can use white space between paragraphs, sections, and chapters to chunk content for users. White space shows where ideas begin and end. Furthermore, the amount of white space between paragraphs and sections as well as between sections and chapters shows readers how to group information.
For example, placing white space between paragraphs and more white space between sections than between paragraphs indicates not only that the information is each paragraph is a unit of thought, but also that the paragraphs themselves form a larger unit (a section).
In addition, you can use white space vertically to indicate the relationship among ideas, particularly a hierarchical organization. By indenting portions of the content, you visually illustrate that the indented information is secondary to information not indented. In this way, you can indicate main ideas and subordinate ideas as well as general information and specific information.
By setting off items such as headings and listings with white space, you also increase the effectiveness of your organization by helping users visually find information quickly and easily.
Highlighting
Common techniques for highlighting include using underlining, boldface type, italics, capital letters, and color. You can reinforce highlighting techniques by using white space and horizontal or vertical lines to make readers aware of important information. Highlighting, like white space and lines, enables you to organize text visually: to indicate different types of information and the importance of particular words and passages.
With highlighting, you can differentiate content. For example in a manual, you can distinguish between instructions (procedures) and expository prose (explanations) by placing one of the two on a light-colored background, such as beige or grey. In addition, you can emphasize important content such as that in notes, cautions, and warnings: first, isolate this important content from other information by placing it in a box; then use white space and highlight appropriately.
Highlighting also emphasizes important qualifying words such as "not," "only," and "if." Placing words and short passages of text in italics, boldface, or capital letters stresses their importance because these highlighting techniques both emphasizes the information and cause users to read more slowly.
Just as with white space and lines, you can overuse and misuse highlighting. Using all capital letters indicates the importance of words and slows down readers, but using all capital letters for lengthy phrases or for sentences lowers readability.
Underlining should be used sparingly for several reasons. Most important, it decreases legibility because it blurs the descenders of letters. It is reminiscent of typewritten, underlined text and thus detracts from professional appearance of documents. An aside — in web pages, underlining indicates an active link, so underlining that is not meant to be a link can be confusing.
Visuals
You can use visuals to indicate organization. In addition, visuals function similarly to headings, allowing readers to skim and scan text. The most common visuals found in computer manuals are flowcharts, tables, computer keys, "boxes," and computer screens. Technical writers and editors need to become familiar with the wide range of possible visuals available as well as which type of visual is best for the target audience.
Flowcharts provide visual overviews that help readers build schemata.
Tables summarize content and present it in a visual format that makes information both accessible and more easily understood than if it is expressed in prose passages.
Visuals such as computer keys, boxes, and computer screens may indicate computer keys that readers press, information that they type, and content that they see on the computer screen. These visuals prevent readers from confusing different types of content. Be sure that you use such visuals consistently to enable readers to form schemata.
Summary
The article that this information is taken from presents a case study discussion of the use of organizational devices in a manual Disc Architext IV-3.1.
In the article, we suggested organizing guidelines and organizational devices that will enable you to write usable, reader-based manuals whose information is accessible. One final suggestion — be sure that you explain to users at the beginning of a manual, and anywhere else appropriate, how you have organized contents and what organizational devices you have used. Users of software manuals aren't interested in figuring out the organization of the manual. Consider in other types of documents when you need to spell out the way you are using organizational devices.