A reading guide makes it easier

Depending on the amount of text and the information needs of the reader, reading a manual is similar to short or long distance running. Long before the race kicks off for the reader and he starts his manual run, we plan the route, highlight the entry points, define goals, secure the route and provide road signs.

However, despite careful planning, anything may go wrong during the run. Even the fitness of the reader plays a role. But much would be gained, if technical editors create the best possible conditions for a successful manual run.

Planning the route

Before we start writing the manual, we plan the thematic route and divide it into more manageable sections. This lets the manual reader cope with the distance later, without running out of steam.

We fix our route plan in a table of contents, which is, however, not the end of it. During the follow-up, we must check and re-check the route: for example, for directness, practicality or stumbling blocks and other safety risks. If necessary, routings must be corrected, more practical ways must be adopted and risks eliminated or secured alternatively. Failure to apply these measures may result in such contents:

On checking this route, it is immediately apparent that the section “General Features” ends with the section “Special Features”. This is anything but straightforward and can irritate the manual reader at the least. If the reader selects the “General Features” section, he certainly does not want to land at Special Features, just as we do not want to find ourselves in the forest during a city tour. And that is just where the planner of the above route got lost by missing the forest for the trees. This is partly due to the complex heading hierarchy, which exceeds the recommended three hierarchical levels by far. No one can understand this then, neither a technical editor nor a reader.

However, the technical writer was not completely wrong, as the information about “System Messages” and “Warning Signals” definitely belongs to “Operating Information”. As usual, the sticking point lies in the structuring and formulation, whereby, well thought out formulations simplify the ordering of the topics. We can change terms, for instance, make the forest into an urban forest in the city tour or turn the "General Operating Information" into "User interface". Sometimes it is also enough to remove unnecessary terms like "Special Features". Ultimately, the table of contents could look like this:

Marking the starting points

The manual reader himself decides which sections he wants to read. To simplify this choice and the section overview for him, we highlight a starting point for each section using headings. The clearer the starting point, the easier it is for the manual reader to find them and fewer "false starts" can be expected.

Among other things, a starting point is clear if it stands out well from the others at the first glance. Under this aspect, the following headings have failed:

Headings that begin with different and distinct terms are more effective:

Starting point terms that the reader is familiar with facilitate the matter further.

Defining goals

One who starts somewhere usually wants to arrive somewhere. So does the manual reader. Apart from his overall goal to operate the product described in the manual successfully, he has a series of intermediate goals in mind, i.e. to overcome some problems with the product. But for him to start in a targeted manner, he needs to know what the end goal is. Headings help in this task by not only providing distinct starting points, but also identifying the respective goal clearly. Moreover, they make it easy for the manual reader to choose his section, because he can compare his own goals with those provided, before starting.

Take the topic "Software Installation". Some only want to read about the basic installation issues in theory while others want to cut right to the chase and start with the practical implementation. Manual readers can thus have different objectives in the same issue. Purely substantive headings, as in the next example, seem more theoretical, allow descriptive text to be expected and give no indication as to whether the respective sections provide installation instructions:

Whereas in this version:

Headings with verbs signal to the reader instructional contents in the chapter. Thus, if we consistently distinguish between instructive and purely descriptive chapters by using or not using verbs, we facilitate the reader's goal orientation.

Providing warm-up phases

Like all runners, guide readers must also warm up: prior to the whole distance as well as before the individual sections. We take this into account by offering introductions to the manual and to each chapter. This allows the manual reader to warm-up to the respective topic and prepare himself optimally for the upcoming run. For example, consider the following introduction to a chapter from a software manual for physicians:

And if there's nothing to say in the preface, the introduction can at least provide an outlook on what lies ahead, i.e. on the structure and content of the manual or chapter.

Increasing requirements gradually

In order to support the warm-up and not overwhelm the reader and let him rise to his top form, the performance requirements should be increased with caution. Therefore, the most difficult and demanding sections should not be right at the beginning.

On one hand, we can generally precede the difficult sections with the easy ones, if the topic of the manual permits it and on the other hand, we should build up knowledge step by step through the information provided in the manual. Both approaches can be seen in the following table of contents, which comes from the instruction manual for an iron:

Take for example, section 3. In contrast to the subsequent section, it is not complex and therefore apparently easier. In addition, section 3 gives basic knowledge, which section 4 can build upon.

Setting milestones

Milestones help the manual reader to keep his bearings during the run. The following, among others, can be used as milestones

• Headers with lively running titles that contain the chapter and section headings
• Highlighted key terms or keywords, ideally as side headings in a marginal column
• Symbols and other graphic design aids
• Operating results in text and image, from which manual readers can closely monitor whether they are still on the right track
• Characteristic paragraph formats

Consider an example of the numbered list as a proven paragraph format for step-by-step instructions or blocks of statements. It meets several orientation features at the same time:

• As a unique identifying feature, the numbering makes it easy to spot the step instructions within the remaining text
• The number of points or numbered steps provides information about the length of the respective operation
• The number of the last executed operation step tells the reader how much of the operation he has already completed and how much still lies ahead
• And should he pause once, he can easily remember from which step he needs to continue later, based on the numbers

Announcing branch operations

Not just milestones help the manual reader to find his way. The directness of the route is at least as important as it is to read with a view of the route plan. But not all routes are straight. Some routes branch out even in our instructions, e.g. in operation alternatives. Take this scenario: Mr. Bright has purchased lights that he wants to attach directly to the ceiling. He opens the supplied installation instructions, in which the following is stated:

Unfortunately, Mr. Bright is discouraged and gives up just after the first sentence, because he thinks the introductory statement is general and universally valid. Mr. Bright is upset and angry at the light seller. Had he not promised that the lights could be installed directly on the ceiling? And now it’s not possible? The second paragraph indeed has the answer to this, but our manual reader does not come this far.

The bottom line is an unpleasant situation. And just for the reason that the technical editor unnecessarily hid an important assembly method behind a long mountain. Instead, he could have announced in the beginning itself that there is more than one way. Mr. Bright would have continued further carefully and found the following:

Securing the route

The route must be sufficiently secure so that the manual reader arrives safely at his goal and does not stumble on the way. In particular, warnings help, but not when they are just behind the stumbling point, as in this example:

With such an arrangement, the reader may not read the warning at all, because he is already “drowsy” after unscrewing the vent cap and it’s all over by then. The following version has an early warning:

The first thing is to put the warning before the “dangerous" operating step. Secondly, it must be ensured that the warning is not overlooked. Using symbols helps to increase the reading probability. This is especially true for readers who like to leaf through manuals quickly.

All clear!

Before we conclude our work, we should check the following points again:

• Are the topics and the sections straight forward and clear?
• Can they be handled with respect to the length and level of performance?
• Are there enough warm-up phases?
• Are the individual starting points easy to find?
• Are the above-mentioned objectives clear and consistent?
• Are there signposts?
• Is the route secured?

Were you able to answer all the questions with yes? Then the manual can be released. And even if we as technical editors seldom experience how it goes for the reader, at least he will know where he is going – thanks to our reading guide.