Make topics self-contained

Print topic Print topic Previous topic  Next topic

Self-contained topics are vital for online help, but they also make printed manuals more user-friendly.

Build topics that are complete, which means that they fully cover what their headings promise to cover.

Within the topic text, don’t use any statements that relate to a given sequence of topics because you can’t presume that users have read any “previous” topics or will read any “subsequent” topics. It’s OK to link to other topics for related information but don’t rely on the fact that readers follow the order of topics that your table of contents suggests.

No:

As you’ve seen in the previous chapter, you must first create a report before you can print it.

Yes:

You must first create a report before you can print it (see “Creating Reports” on page 78).

Self-contained topics have many advantages:

Self-contained topics are essential if you want to create online help and a printed manual from the same text base, or if you want to produce documentation for different product versions from the same text base. You can then omit any topic in a specific version without having any negative side effects.

Writing self-contained topics forces you, the author, to be concise and focused. Sometimes this can be challenging, but it greatly enhances the quality of your writing.

Self-contained topics are a one-stop knowledge shop. Users find everything that they need to know in their specific situation and context in one place. There’s no need to follow links. There’s no need to go on a wild-goose chase and to collect information from multiple places.

Expand /Collapse All Subsections

What’s the right topic size?

Don’t attempt to adhere to a specific topic size limit. Try to keep every topic as short as possible, but as comprehensive as necessary to answer what the heading promises that the topic will answer.

If a topic seems to be getting too long:

Consider splitting the topic if there are different pieces of information that users are likely to need independently. Find new headings that clearly describe the contents of both topics. If you create online help, add related topics links between both topics.

Layer the information. Add subheadings. In online help, create expandable sections (toggles). See Layer information for details.

How much scrolling is acceptable?

If readers are truly interested in the content, up and down scrolling is no problem. However:

You must gain the readers’ interest with the content that’s visible without scrolling.

You must keep the readers’ interest throughout the whole text, or they’ll stop scrolling and leave the topic without even having seen the rest.

Therefore, good general rules are:

Start each topic with the main information.

Make sure that the main information is visible without scrolling.

If it’s possible, use expandable sections (toggles) to layer the information. If readers can grasp the structure of the topic at one glance, the topic isn’t too long.

The more important a piece of information is, the closer it should be positioned to the upper left corner of the window.

Don’t add any extra wide tables or extra wide pictures that require horizontal scrolling. Vertical scrolling is acceptable, but horizontal scrolling is not.


Find meaningful headings