Add labels (subheadings)

Print topic Print topic Previous topic  Next topic

Start each new section with a label that clearly communicates what the section is about.

In a printed document, labels often appear as subheadings or as subtitles in a margin column. In online help, labels often appear as subtitles as well, or they are clickable headings of expandable sections (toggles).

Readers benefit from the labels because the labels work as landmarks that enable them to skim a text for specific information and to decide beforehand whether to invest the time in reading a particular section.

As the author, you also benefit from the labels:

Labels give you a constant overview of the structure of your document. You can quickly see where the best place is to add new information.

Labels minimize the risk of mixing subjects (see Don’t mix subjects). When writing, you can constantly check your text against the label. If the text doesn’t fit under the label, this indicates that you should put the information somewhere else.

Expand /Collapse All Subsections

How to phrase a label

You can either use a short sentence or statement as label text, or you can write the label like a heading.

Make sure that the label text is concise and easy to read.

Make the label meaningful. The label should clearly communicate:

what the section covers (the subject)

what kind of information readers can expect (concept, task, or reference)

what level of detail is given (basic information for beginners or details for advanced users)

If the surrounding topic doesn’t mix information types but is clearly either a Concept topic, a Task topic, or a Reference topic, labels can be very short and don’t have to communicate the information type again. For example, if the surrounding topic is clearly a Task topic, it’s evident that subsections also cover tasks.

If the surrounding topic mixes various information types (generally not recommended), you need to find labels that communicate the information type of each section as well. For example, you could use phrases such as “How to print …” or “Printing …” to indicate that a section contains a procedure; compare Structuring: Find meaningful headings.

How many sentences and paragraphs should go into one labeled section?

There’s no general rule about how many labels you should add. A good average is somewhere between 2 and 7, but this largely depends on the subject.

As rules of thumb:

Never mix different subjects within one section under the same label. If there’s a new subject, start a new section.

When in doubt, it’s better to start a new section with an additional label than to have a section that’s longer than half a page.

A section may contain a single paragraph or multiple paragraphs. The paragraphs may all be of the same type (such as procedures) or of different types (such as body text, a procedure, and a warning).

Establish a consistent labeling scheme

When possible, establish a consistent way of structuring your topics and of labeling the sections within these topics. This adds consistency and parallelism (see Be consistent and Be parallel).

For example, you could:

always use the sections “Requirements,” “Steps,” and “Results” in Task topics

always use the sections “Purpose,” “Syntax,” “Input,” “Output,” and “Parameters” in a particular kind of Reference topic

Note that it depends on your specific product and use case which labels work best.


Don’t mix subjects

Structuring: Layer information

Structuring: Find meaningful headings

Structuring: Tips for writing headings

Designing: Subheading paragraph styles