The following table suggests ways to structure an online document. These structures are not mutually exclusive. You can use these high-level and low-level organizational strategies together in the same document.

In an online document organized by hierarchy, high-level generalities and overviews offer a preview of what lies below. Levels within hierarchies can be based on importance, frequency of use, or complexity.

Be careful not to create too many hierarchical levels that bury important information. You must balance the need to divide text into short, self-contained topics against the risk of creating valueless intermediate screens.

In a technical manual that is organized by hierarchy, the top three levels serve as a clickable table of contents from which readers can jump to various topics. Within the text of the document, readers can jump to related material, both in and out of the document, through links.

In the following example, a plus sign indicates that a topic contains hidden subtopics. The underscores indicate links.

When organizing by inverted pyramid, you place the conclusion and a short summary of the main ideas at the beginning of the topic. The details follow in decreasing order of importance. Readers can digest the main points even if they stop reading before reaching the end of the document.

The inverted pyramid structure, typically used in newspaper writing, is also appropriate for long narrative text in online technical documents. Use this structure to organize paragraphs and sentences within a section of narrative text.

To create an inverted pyramid structure, follow these guidelines:

The following text begins by defining “device driver optimization.” The text then provides links to sections that describe three types of optimization guidelines: general, transmit, and receive. Details appear later in three separate subsections. If long enough, each section could be divided into one or more separate pages.

Tables are an effective way to compare facts and enhance reader comprehension. However, tables with many rows and columns can be difficult to read and display online. Make online tables short and simple to improve online readability and reduce load time.

If readers are likely to print a table for future reference, make sure that the table does not run off a printed page.

To simplify tables, follow these guidelines:

When formatting tables, leave room for the expansion that can occur during translation. For more guidelines on constructing tables, see “Tables” on page 42.

In this example, the table helps readers make decisions about tasks that they need to perform and provides links to additional information.

Use clickable flow diagrams to direct readers through related topics. For instance, you can use flow diagrams to lead readers through a complex task consisting of multiple procedures. Links can take readers to step-by-step instructions for each procedure.

If the product you are documenting lends itself to a high-level overview, you can use a flow diagram to show how groups of procedures are related. This strategy can help give readers the “big picture” of the product.

When formatting flow diagrams, leave room for the expansion that can occur during translation.

In the following example, a clickable flow diagram with four links helps users troubleshoot the workstation in reference to the OpenBoot™ PROM report.

Example 4-4. Organizing by Clickable Flow Diagram

This example shows a flow diagram with eight links. The diagram is intended to help users get started with the system and its preinstalled software.

Example 4-5. Organizing a Complex Task by Flow Diagram

Task maps organize task-based information for users who need fast access to procedures. You can organize individual tasks into a task map that lists either of the following:

Links to each procedure create a clickable task map. A link to overview information directly before or after each task map enables readers to view overview material only if they want to do so.

A task analysis can help you determine which tasks are best grouped. Ideally, include on your analysis team users who perform these tasks.

See also “Using Task Maps to Organize Tasks” on page 120.

The following task map provides links to procedures and high-level descriptions for quick reference. Tasks are numbered because they must be performed in sequential order. Note the link to overview information that follows this task map.

For an overview of managing quotas tasks, see __Managing Quotas (Overview)__.

Divide each document into self-contained, linked topics. Ideally, each topic explains its content without making assumptions about previous topics. Links to overviews or other explanatory information can help readers who need more background.

To determine how much information to put in a topic, consider the complexity of the information and your audience’s knowledge and experience.

Make each topic clearly focused and coherent so that it answers one question about one subject for one purpose. Try writing a single question that the topic is meant to answer. Then, judge whether the content in that topic fully answers that question.

Also, repeat contextual information within each topic when needed. Contextual information helps orient readers so that they know what the current topic is and how it fits within the larger document structure. See “Preserving Context in Online Documents” on page 98.

Short topics and the frequent use of subheadings might at first appear undesirable from a visual design standpoint, depending on the display tool and the reader’s browser preferences. If the document is single-sourced and also delivered in print, so many subheadings might appear cluttered on the printed page.

However, many subheadings make text more scannable for readers scrolling through a document. Subheadings also help readers more easily locate specific information in a clickable table of contents. Instead of being concerned about how the formatting is rendered in print and online, focus on the structure of the content. Divide text into short, self-contained topics. Then, label the topics with meaningful headings and subheadings.

Short, uncomplicated sentences are especially important online because reading text on a screen is slower than reading printed text. To present information clearly and simply, follow these guidelines:

Short paragraphs offer visual breaks and are easier to scan and read online. To keep paragraphs short, follow these guidelines:

To determine what material is unnecessary, you need to know not only what readers need, but what they do not need. To reduce word count, follow these guidelines:

Do not make text so short that it seems “dumbed down,” choppy, abrupt, confusing, or incomplete. You do not want to sacrifice content, readability, quality, tone, or flow.

Most importantly, do not remove content that readers need to complete necessary tasks. Also, if topics can be read in any order, you might need to link to or repeat some information to provide sufficient context for readers. See “Preserving Context in Online Documents” on page 98.

Remember that online writing does not always have to be short. Drastically condensing text can disappoint readers who are seeking very detailed information online. Readers prefer documents that fully answer their questions on a topic. For in-depth answers, readers are likely to print the document anyway.

Write headings and subheadings as short, precise abstracts of their associated content. Headings are often displayed out of context in a search results list or bookmark menu. Sometimes only the first few words are displayed, or the words in the middle of the heading are truncated and replaced with ellipsis points.

Even when headings are displayed with their associated content, the small amount of information visible on a computer screen is difficult to interpret at a glance.

To construct scannable headings, follow the guidelines in “Headings” on page 32.

Bulleted lists are ideal for online documents because they emphasize information in a concise format that encourages scanning. Key facts within list items are easy to identify. Bulleted lists also help hard-to-read screen text and provide white space that gives the eyes a visual break.

To facilitate scanning, follow these guidelines:

For more guidelines on constructing lists, see “Lists” on page 35.

A jump list provides a clickable list of topics that helps readers scan and navigate in an online document. Use a jump list so that readers can easily scan and link to the following:

When you create a jump list, consider briefly explaining the content of each list item so that readers can decide which links to traverse. Annotating links is not necessary if the link text clearly describes the link destination.

For more guidelines on constructing jump lists, see “Writing Jump Lists” on page 41.

In an online environment, you usually do not know how readers come to your document or a section of it. They might arrive through a table of contents or a search engine. They might click on a cross-reference that leads them there. They could just be scanning links.

When you make few assumptions about reading order, you are better prepared to offer readers the necessary contextual cues.

Contextual cues help readers understand where the information belongs within the larger structure of the document.

If you do not provide sufficient context, readers have to figure out how the sections are related. You need to help readers make these associations meaningful. For example, you could indicate to readers that a certain topic is part of a broader topic.

For instance, to indicate that information under a third-level heading is a subtopic of a second-level heading, you could write the subtopic heading to reflect this relationship. Or, you could include introductory text to this effect.

If sequential order is important, give readers a sense of what comes before and after a topic. For example, if a complex task is logically divided into several short subtasks or procedures, tell readers what comes before and after each procedure. A list of prerequisites before a procedure and a “Where to Go From Here” section after a procedure would suffice here.

The words “above” or “below” have no meaning in a document that is not read linearly. Instead, use one of these strategies: