Find meaningful headings

Print topic Print topic Previous topic  Next topic

Don’t let your readers guess what’s in a topic. Create headings that clearly communicate:

the contents of a topic

the topic’s information type (concept, task, or reference)

if there are different user groups, or if the topic is relevant only for advanced users: the audience of the topic

It’s a good idea to learn from marketing: Use a heading that attracts the attention of readers. However, don’t promise anything that the topic cannot deliver.

If users feel that a topic answers just what they thought it would answer, you’ve created a positive user experience.

If users feel that a topic doesn’t answer what they thought it would answer, they will conclude that the whole document is useless and stop reading. Many of them will never, ever come back. This is the worst thing that can happen!

Be aware of the fact that readers don’t always see a heading in its hierarchical context. For example, when you browse the table of contents in a book and there’s a main heading “Printing” and the subheadings “Overview” and “Reports,” it’s obvious that the Overview topic is about printing and that the Reports topic is about printing reports. However, when users find the same topics via a link or via search in online help, the heading “Overview” appears isolated and practically says nothing at all. Users don’t have any clue then that it’s an overview about printing. With the Reports topic, the problem is very similar: Is it about reports in general? About designing reports? About creating reports? About sending reports by email? Headings that are more meaningful are “Printing Overview” and “Printing Reports.” It’s perfectly OK to repeat the major heading “Printing” within the headings of the subordinate topics.

In addition, in online help, topic titles are typically listed as the results of full-text search. If you have multiple topics with an identical title such as “Overview,” users have no clue which “Overview” to choose.

Here are some typical examples of popular but meaningless and often ambiguous headings that you should definitely avoid:

Overview

General Information

Guidelines

Basics

Procedures

Results

Reference

Additional Information

Miscellaneous

Use headings that are more descriptive, such as “Configuration Overview” instead of “Overview,” or “Safety Guidelines” instead of “Guidelines.”

Expand /Collapse All Subsections

How to communicate the information type via the heading

By using typical grammatical constructions and typical phrases, you can often effectively indicate whether a topic contains basic conceptual information, step-by-step procedures (tasks), or detailed reference information.

Typical titles are:

for concepts: … Basics; How …; Where …; When …; Why …

for tasks: …ing …
(for example, Printing Reports)

for reference information: … Reference
(for example, Parameter Reference)

Note:
Many writers use headings that begin with “How to …” for topics that describe tasks. Using the gerund (…ing) form, however, is usually shorter. Also, it automatically moves the important words to the beginning of the phrase. Users then don’t have to read the complete heading to grasp its meaning. Another advantage with using the gerund form is that when multiple headings are listed below each other in the table of contents, it doesn’t happen that all headings start with the same phrase “How to...”. See also Tips for writing headings.

It’s OK to use a question as a title

If you can anticipate what questions users will have, you can often use these questions as topic titles. The advantage of this approach is that you automatically create topics that exactly match the users’ need for information. This motivates users to actually read your document and works particularly well in documentation for consumer products.

No:

Exerting influence on fuel consumption

Yes:

How can you save fuel?

Using questions as titles is also a good method if you expect that users may have reservations about the points that you make. You can then phrase these reservations as questions and deal with them directly.

If you don’t want to use questions explicitly, you can transform them into statements. Often, you can even include the answer or the key message of the topic this way.

Yes:

Is it OK to use a question as a title?

Top:

It’s OK to use a question as a title

Top:

Why it’s OK to use a question as a title


Make it goal-centered

Layer information

Make topics self-contained

Tips for writing headings

Designing: Heading paragraph styles

Designing: Subheading paragraph styles