If your product is complicated to understand or operate, the manual is likely to be extremely detailed and therefor quite extensive. When a manual runs to hundreds of pages, customers have the challenge of finding the information they need in the manual.

A table of contents is generally a good start, but often does not lead directly to the information required by the reader.  An index is even better, but an index takes a lot of work to set up, may not include the specific references some readers are looking for, and can easily become inaccurate as the product and therefore the manual evolve.

A good compromise between the readers’ needs and reasonable production costs (and time lines) is to provide ample cross references throughout the manual.

Deciding Where to Put Cross References

Deciding where to put cross references in a manual is more of an art than a science.

The author must anticipate what questions readers may have as they read the manual, and then intelligently add cross references to related sections, even if the sections are not yet written.  This usually means thinking about information, procedures and functionality that is related to the material as it is written.

A balance must be struck between having enough cross references to make the document easy to navigate, yet not having so many that the document becomes cluttered.  There is a risk that too many cross references might confuse the reader, or force them to hop around the document, covering a lot of ground but absorbing little substance.

Adding cross references is somewhat laborious, and it can break the flow in the author’s mind as the document is being written, so adding too many cross references is rarely a concern.

Cross References and Documentation Maintenance

There is also the issue of maintaining the document.  As the product evolves, the manual must be amended to keep up.

Many products, especially software, have numerous common elements that need only be described once, yet they are relevant to numerous subjects covered throughout the manual.

Rather than providing the same information at various points throughout the document, it is much easier to explain something once, and then provide a cross reference to it as the need arises.

This can cause challenges when it comes to managing the architecture of the document.  Sometimes it seems unfair to force the reader to navigate the document extensively in order to understand the product. It can also make the structure of the document quite awkward if done carelessly.

Conclusion

Cross references are a great help to the reader in their search for specific information.  It also greatly aids the production of a complete and accurate document, even as the product itself changes over time. They can cause challenges during production but are well worth the effort if you care about the readers’ needs.

If the manual is extensive, cross references greatly improve the usability and maintainability of your technical documentation.