The users of a product don’t read technical documentation for fun.
▪Users want to find what they need to know as quickly as possible. ▪Users want to stop reading as soon as possible and get back to work. Don’t bother your readers with any information that they don’t need.
Layer your information according to your readers’ needs.
|
Expand /Collapse All Subsections
The following example illustrates a combination of some frequently used layering techniques:
▪Each topic within the document belongs to a dedicated information type: “Concept,” “Task,” or “Reference.” ▪In the table of contents, each information type has a specific icon. ▪The links to related information at the end of the topic are grouped according to the same information types. ▪General information that’s important for all users is always visible. It starts with the most important points. ▪Additional information that’s only important for a minority of users or in a minority of cases is put aside in expandable sections. If users want to see it, they must explicitly unhide it. ▪Different aspects of information are layered in tabs.

|
How and where you should layer your information depends on your product and on your audience. Only what the users of your product want to know at the same time should end up on the same layer.
For example, users rarely need conceptual information, procedural information, and reference information all at once.
▪A user who needs to perform a particular task wants step-by-step instructions, but no verbose general information. ▪A user who is already in the middle of a procedure only needs a detail about a particular parameter, but no step-by-step instructions. ▪A beginner needs basic concepts but may be overwhelmed by too many details. If you cram all information into one block instead of layering it, each user must also read a significant proportion of text that doesn’t interest him or her at all. As a result, users feel that the document doesn’t really meet their needs and get upset about the time they’ve wasted.
If you layer the information, however, users only read what actually interests them for their specific situation. They feel that your document exactly answers their questions and will come back for more.
|
The most frequently used layering criteria are:
▪importance (must know, should know, and optional) ▪information type (concepts, procedures, reference information, and examples) ▪user groups (developer, administrator, and end user) ▪expertise (beginner, intermediate user, and advanced user) |
If you provide more than one document, layering can begin even on the document level. For example:
▪If you provide a user’s guide and an administrator’s guide, for example, this layers your content according to different user groups. ▪If you provide a user’s guide and a reference guide, this layers your content according to different information types. Only include the information in each document that’s in line with the document’s information type.
See also Which documents?
|
When layering on the topic level, you create topics that exclusively contain information of the same information type.
The most frequently used topic types are:
▪concept (provides basics; answers “why?”) ▪procedure (provides tasks; answers “how?”) ▪reference (provides details; answers “what?”) Depending on your particular project, you can create any custom topic types that make sense. A topic type makes sense if you expect that a significant proportion of users will be interested exclusively in the information of this type without looking at other information.
For example, when documenting an ice cream machine, having only one “reference” topic type may not be enough. Instead, you can create the custom topic types “recipe reference” and “technical reference.”
Tip:
In general, don’t use more than 3 or 4 different information types. Users must be able to distinguish them clearly, which is rarely the case when using more than 3.
To organize layered topics within the table of contents, you have two options:
▪You can create separate chapters where you collect all concepts, all procedures, and all reference information. ▪You can list the topics of different topic types next to each other, typically in the following order: concept > procedure > reference information. In most cases, this option is more user-friendly because it keeps related information close together. Note:
Use headings that make clear to which topic type each topic belongs (see Find meaningful headings).
Example:

|
Within a topic, you can create subsections to separate different layers of information.
Start each subsection with a descriptive subtitle that clearly communicates what the subsection is about. Readers can then easily skim the text just by reading the subtitles.
In online help, you can create expandable sections (toggles) as a layer for initially hiding information of minor importance:
▪Create the topic so that information that all users need is always visible. ▪Put all information that only some users need into an expandable section. Another option in online help is the use of tabs, with each tab showing a different information layer.
You can use tabs, for example:
▪to separate concepts from procedures and from reference information within the same topic ▪to separate different types of reference information ▪to separate different kinds of examples |
Many writing rules for writing clear paragraphs and sentences are essentially also about layering. The common principle is always the same: Confront the reader with as little irrelevant information as possible.
The most important layering rules on the text level are:
▪Always start with the main point. Start with what most users need to know, what users need to know early, and what’s not optional. ▪Don’t mix different subjects within one paragraph. If there’s a new subject, start a new paragraph. ▪Don’t mix different ideas or actions within one sentence. If there’s a new idea or action, start a new sentence. ▪Avoid all sorts of parentheses and nested sentences. If a parenthetic remark actually is important, create a full, separate sentence. If the parenthetic remark isn’t important, omit it. |
In online help, you can also layer links to related topics.
For example, if you have the three topic types “concepts,” “procedures,” and “reference information,” instead of providing one long list of related topics, you can provide three shorter lists:
▪one list with links to related concepts ▪one list with links to related procedures ▪one list with links to related reference topics |
|