Technical Writers’ Companion

Always left align headings. Don’t justify headings even if your body text is justified (not recommended).

In general, use the same font as for all other styles. If the used font is very wide, you can optionally use a related, narrower font (siehe Which font?). In most cases, however, it’s enough to slightly reduce the character spacing as part of the character settings.

Don’t use small caps because small caps significantly slow readers down.

In online help, use the same heading style for all topics, regardless of where a topic stands in the hierarchy of the table of contents.

In a printed document, increase the visual weight depending on the heading’s hierarchy level. Make h1 more prominent than h2, and make h2 more prominent than h3.

To increase the visual weight, you can:

▪use a larger font size

▪use bold font style

▪use color instead of black or gray

▪add space above the paragraph

Add more space before the heading than after the heading. Don’t make the space after the heading larger than one line of text so that it’s clearly visible that the following text belongs to the heading.

If you have a small type area, you can’t avoid having headings that run across two lines. Make sure that the line spacing is visually smaller than the space below the heading. Bear in mind that the larger the font is, the smaller the relative line spacing should be (siehe What line spacing?).

If you want to separate the distinct sections of your document very clearly, you can add lines or background colors to headings.

If you want to bring some color into your document, an unobtrusive way of doing so is to give level 1 headings (h1) your corporate color or the predominant color of your product logo.

Anmerkung:
If you use color here, also use the same color in the table of contents (siehe Table of contents page layout).

In online help, heading numbers don’t make any sense at all. In hypertext, essentially there’s no given hierarchy and sequence—even if you have a table of contents as a navigation tool.

In printed manuals, chapter numbers are often included:

▪because the authoring tool can do it automatically

▪because chapter numbers are common in scientific textbooks, and these books are what developers and engineers are used to reading

Neither point is a good reason to use heading numbers. In user assistance, chapter numbers usually have more disadvantages than advantages.

The advantages of having chapter numbers are:

▪Chapter numbers indicate the headings’ hierarchy level. (However, if you have well-designed heading paragraph styles, this extra visualization shouldn’t be necessary.)

▪Support staff often prefer referring callers to chapter numbers rather than to page numbers because chapter numbers change less often when a document is updated.

The disadvantages of having chapter numbers are:

▪Chapter numbers add clutter to the page without adding valuable information. In particular, chapter numbers clutter the table of contents, which makes it more difficult both to grasp the overall structure and to find a specific topic.

▪Chapter numbers create the look and feel of a scientific paper, of a complicated textbook, or of legal text, instead of a document that’s meant to encourage reading.

▪In many authoring tools, numbered headings are significantly harder to handle and more error-prone than headings without numbers.

Tipp:
Even if you do decide to number headings, you don’t have to number the headings of all hierarchy levels. For example, you can number heading levels 1 and 2 but not number heading levels 3 and 4. This can help to make your table of contents much clearer. At least it avoids the longest, most difficult-to-read numbers.

If you number headings, don’t include a period after the last number.

Don’t use Roman numerals. Many readers don’t know how to read them. Also, Roman numerals are longer than Arabic numerals.

If you number headings, format the numbers less prominently than the heading text. For example, make the numbers gray and less bold than the heading.

If you add automatic page breaks before headings so that each topic starts on a new page, this can save you a lot of manual work when fine-tuning the final formatting of your document.

The downside of beginning a new page for each topic is that it can make your document longer and adds more unused white space at the end of topics (for details, see Automate line breaks and page breaks).

As rules of thumb:

▪If your document is shipped electronically and you don’t expect most readers to print it, start all headings on a new page.

▪If your document is shipped on paper, or if many readers will print it:

▪Start at least headings h1 und h2 on a new page.

▪Start all other heading levels on a new page only if the majority of topics isn’t shorter than half a page. Avoid having an average of more than 30% of white space on your pages.

h1

▪Set to keep with the next paragraph on the same page.

▪Set to keep all paragraph lines together on the same page.

▪Automatically add a page break before the paragraph.

If you have a layout with right pages and left pages, set up the style so that it always starts on a right page (that is on a page with an odd page number).

h2

▪Set to keep with the next paragraph on the same page.

▪Set to keep all paragraph lines together on the same page.

▪Optional: Automatically add a page break before the paragraph.

h3

▪Set to keep with the next paragraph on the same page.

▪Set to keep all paragraph lines together on the same page.

▪Optional: Automatically add a page break before the paragraph.