3   Structure and Organization

Cross-Referencing and Linking

In a print manual, we refer the reader to other parts of the manual, or to other documents, by using a cross-reference. In an online manual, the reader can usually click on the reference and jump directly to the referenced section or document without turning pages.

Cross-References in Print

Try to organize and write your manual so that cross-references to other parts of the manual are needed only occasionally for information that is essential to the topic being discussed. Many readers will not take the time to locate the referenced information. Readers should not have to look up information to complete a procedure, for example. If your manual has too many cross-references, restructure it. Never cross-reference warning or caution notes—always repeat them each time they apply.

On the other hand, avoiding cross-references altogether may force you to repeat large sections of the text, such as a series of steps that is common to several procedures. Having to repeat large blocks of text will increase the size and printing cost of the manual, and reduce the likelihood that people will use it.

Start a cross-reference by telling readers why they should look elsewhere, not where they should look. For example, “For more information on using cross-references, see page….”

Cross-references are a particular problem in revisable manuals since you’ll have to keep track of them when you revise the manual. If you tell the reader to see page 3 of another module, and later on you revise the other module, your cross-reference may no longer be correct. Many authors keep a log of cross-references that they can refer back to later when they’re revising the manual. See Table 3-1.

Table 3-1: Sample cross-reference log

Cross-References Online

If you’re planning on putting your print manual online, you can use your word processor’s automated cross-reference feature to insert the cross-references. This way, when you convert the word processor files to online files, your conversion software may be able to automatically insert links. For automated cross-references to work, however, all of the files that make up your manual must be joined together into one file, or they must be linked together using your word processor’s master document feature (for more information, see Creating a Master Document).

Links in Online Manuals

In online manuals, cross-references do not have the same disadvantages as they do in print manuals. Readers don’t have to thumb through pages, they just click on the reference, so they are more likely to click to the referenced information. Because of the ease of clicking and linking related information, not just within a manual, but between different manuals, most developers of online manuals will include far more cross-references than they would in a print manual. Don’t go overboard, however. The clutter of links of marginal use will obscure the useful ones.

Since online links are usually indicated by coloured and underlined text (except when linking from graphics), cross-references do not necessarily need to be cited explicitly. You can simply link a keyword to the related information source. Make sure, however, that it’s clear what information the user will find.

If you are creating both print and online versions of the manual, as you write and insert cross-references, consider how the cross-reference will appear in both versions. For example, “see page 12,” “see the previous section,” or “see Appendix 2 at the back” won’t make sense in an online manual.

Most software for creating and maintaining sites allows you to automatically check and update your links. For large revisable manuals with many links, this is an essential feature.