Conditional Cross-Reference Labels for Numbered Headings

Article contributed by  John Irwin, Senior Technical Writer / Information Developer, and author.


Find out how to set your heading cross-references free. This article solves a perennial problem with cross-references that technical writers have encountered in technical documents that use numbered headings. The article:

The Problem

A widespread practice in technical documentation is to use numbered headings, and when referring to these headings, to identify them with an electronic cross-reference that includes the heading number and heading text. Electronic cross-references are not hard-coded and so do not require individual maintenance to update them. If you change the heading text, the heading cross-reference will automatically be maintained when you update the fields in the document.

A common convention in these documents is to use different labels to refer to the heading based on its heading level. Heading 1s are typically known as Chapters, while subheadings below that (Headings 2-x) are known as Sections. If a heading is non-numbered, its label may be Topic, or something else, or it may even have no label. Examples of cross-references to four different heading levels:

See Chapter 1: Introduction.

See Section 1.1: Features.

See Section 1.1.1: Standard Features.

See Topic: Hardware.

See Topic: Software.

See Section 1.1.2: Add-On Features.

The label (e.g., Chapter, Section, Topic) is part of the supporting text for the cross-reference, which also includes the introductory clause ("See" or "For details, see..." and so on), delimiters between the elements, and punctuation. These are the elements of a structured cross-reference.

Although it is sometimes done, the label is not usually a part of the heading numbering because it would result in very busy and cumbersome looking headings. In this type of documentation, most people prefer a simple heading number rather than a label and number inherent in each heading.

The problem is that if you change the heading level or promote or demote it in the heading level hierarchy, the cross-reference does not get updated with the appropriate label. Using the example above, if you promote heading 1.1 Features to the chapter level by tagging it with Heading 1 style, the updated cross-reference will read: "See Section 1: Features" rather than "See Chapter 1: Features". These incorrect labels would then require some type of special intervention to update them, such as manual updating or a repair macro.

Many writers try to get around this by adopting a generic label for all heading levels. One generic label that is frequently adopted by writers is Section. This avoids the need to update the labels, but there are still those purists among us who find it an awkward though expedient solution. A chapter is still a chapter after all, no matter how many people call it a section, and there's no use trying to convince these traditionalists otherwise.

The methods described here provide a solution to this problem.

If you use the conditional cross-reference labels as described here, they will be unaffected by any future changes you may make to the headings in the heading level hierarchy. That is, you may move, promote, or demote them in the heading level hierarchy without needing to change the labels.

This article also contains some helpful information on creating structured cross-references.

Due to the length and complexity of this article, it is not really suitable for conversion to a web article.  The author has provided a downloadable package that contains the entire article in Word .doc and PDF formats, plus supporting templates and samples.  Click here to download it.