3   Structure and Organization

Text Hierarchy and Headings

The text in most manuals is organized into a hierarchy—it’s divided first into chapters, then into sections, then into sub-sections, and so forth. Headings are used to label each ‘chunk’ of the text. Heading numbers or the physical appearance or placement of the heading (its attributes) identify its place in the hierarchy. Notice the way headings are used this guidebook.

Text Hierarchy

Most technical writers today limit the number of levels in the text hierarchy to three or four to avoid confusing the reader (see Figure 3-1). You’ve probably seen publications that went much deeper than this. In print publications, where the content must ultimately be organized into a linear sequence to print onto pages, deep hierarchies confuse rather than clarify the relationship between parts of the text. This guidebook uses four levels of headings.

Figure 3-1: Avoid heading hierarchies more than four levels deep

Look at the headings used in this guidebook. Our chapter headings (heading 1) are big and bold. The hierarchy allows manuals to be searched easily and makes the relationship between different parts of the manual clear. The heading attributes visually identify each heading’s place in the hierarchy. For more information, see Heading Attributes.

It’s better to have too many headings than too few. Aim for at least one or two headings on each page. Lots of headings help readers find the information they are looking for. Too few headings require readers to slow down and read text they may not be interested in.

Choosing Headings

Headings are the labels we apply to sections of text so that readers know what information they contain. To be effective, they should be short and descriptive. Avoid, where possible, the following kinds of headings, which identify the type of information, but not the topic:

• introduction
• overview
• general
• miscellaneous
• more information
• policy
• procedure
• standards
• guidelines
• reference

Here are some tips on using headings:

• If the section covers a task, use a heading with a gerund (verbs ending in -ing), such as “Printing Your Document.” If the section describes something, use a descriptive heading, such as “How a Laser Printer Works.”

• Construct your headings in a parallel fashion. For example, if one heading starts with an imperative verb, such as “Print,” they should all start with imperative verbs. If one is a short phrase without a verb, they should all be.

• Keep headings down to four or five words, if you can. Certainly no heading should run onto a second line. Think of them as sign posts along the highway—if they are too long, they can’t be scanned easily.

• Don’t repeat the wording of a higher-level heading in a sub-heading.

• Don’t start headings with an article (a, an, or the).

• Try to have at least two headings at each level you’re using—avoid dividing a section into a single sub-section.

• Repeat the subject in the paragraph below the heading—don’t use a pronoun such as this or it to refer to words in the heading.

• Test your headings by having readers review the table of contents and then asking them if they know what would be found in each section.

Hierarchy and Headings in Online Manuals

In online manuals, you can structure information in many more ways than in print manuals (see Figure 3-2). For example, you could link descriptions of each of your organization’s departments to an organization chart. When the box for a department is clicked, a detailed description of the department would appear, either replacing or sitting on top of the organization chart. Within each description, you could include a list of positions that make up the department. When a position title is clicked, the job description would appear. When a job description appears, a list of people with that job title could appear. The ability to link to other information in numerous ways allows for different ways of organizing and locating information than is possible in print publications.

Figure 3-2: Example of ways to link information online

The structure of online information sources is often web-like, consisting of information topics (units of information) and various links between them (see Figure 3-3). Most exhibit a hierarchy in the sense that they have a starting point, the homepage, and pathways to all information topics within the system. The number of clicks required to get to information topics (not just more menus) can be numerous. However, try to limit the number of clicks from the home page to the topics to around five, so the user doesn’t give up on finding the information.

It’s also possible, but not recommended, to have an online information resource with no hierarchy. Imagine a large pool of information topics with no direct links to them, but accessed with a search engine and index.

Figure 3-3: Many online systems have a web-like structure consisting of topics and numerous links

Most online manuals benefit from a clear hierarchy of information. Often the home page lists the chapters. Clicking on a chapter leads to a list of sections. Clicking on a section leads to a text topic. The topic carries a heading at the top identifying its contents, and may have additional sub-headings within the topic. See Figure 3-4.

Figure 3-4: Sample table of contents and text topic

If you need both print and online versions of the same manual, both versions should have the same hierarchy and use the same headings to avoid confusing readers who use both forms of the manual. If you have different structures, you’ll probably have to create two separate sets of electronic files—one for the print manual and one for the online manual.

To plan the contents of the online manual, map out the structure. This can be done either like an outline, or diagrammatically with boxes representing topics and arrows representing links. For more information, see Mapping an Online Manual.