Cross-referencesOctober 15, 2012
One of my colleagues asked me some questions about cross-references.
But first, a bit of backstory…
We’re preparing a very large Word document (800+ pages) and each Section (about 18 of them) is being prepared by a different author. At some point, I will have the job of bringing these individual Sections (aka chapters) together into one BIG Word document prior to it going out to the printer and prior to it being PDF’ed and put online for public distribution and comment. I’ve designed the Word template and the styles to make this job easier; I’ve tested the process of compiling the document’s Sections; and I’ve documented the ‘gotchas’ I’ll have to watch out for.
In the meantime, the authors have been beavering away on their Sections. One of the ‘best practice’ things they’ve been doing is inserting automated cross-references for tables, figures and subsections WITHIN their Section, and inserting plain text Section/subsection/table/figure numbers and captions/headings for what will eventually be automated cross-references to other Sections once the document is a single document. It will be my job to create the automated intra-Section cross-references.
But there must have been some discussion in the office about the number of these cross-references to other Sections — perhaps authors were finding it cumbersome to add them, perhaps they were concerned about the readability of the document when it was peppered with cross-references within the text. Maybe something else. So my colleague contacted me to get my advice.
Here’s a summary of my response:
- Consider WHY you have a cross-reference (x-ref) to another section, table etc., whether it’s to something in the same Section or in a different one. The bottom line is that x-refs to a Section/subsection help you avoid repeating the same information in multiple places, or refer to a table/figure that follows or has gone before that provides the information the reader needs to make sense of the narrative.
- Consider HOW a reader will approach a x-ref. In print, they have to flick the pages to find the supporting information, but in online (PDF) they only need to click the link to go to the relevant part to read the information, then can click back to return to where they were. Clicking a link is a simple process for the reader, though going back in a PDF is not quite as straightforward. (See my blog post about this from 2010: http://cybertext.wordpress.com/2010/07/06/acrobat-back-and-forward-buttons/)
- Consider WHEN to insert a x-ref or not. If the reader MUST know about something that’s gone before or is to come (e.g. Section 8 Assessment Method) to properly inform the current section, then a x-ref is necessary. Likewise, if the data that supports a claim is held in a table or figure, then a x-ref to that table/figure is necessary. However, if the x-ref is a ‘nice to have’ and just offers a link to related (but not essential) information for the reader, then the author has to decide whether to include it or not.
- Consider WHERE to insert a x-ref. Essential x-refs to other Sections and to tables/figures should go as close as possible to where the referring information is written (which is what you do now). However, for the ‘nice to have’ related x-refs that aren’t essential, consider whether breaking them out into a sidebar/box/list at the bottom of the Section/subsection might be more useful to the reader than peppering them throughout the narrative. If you do pursue this option, make sure the [government regulators] are happy with the idea first and that there’s nothing in the requirements documentation that prevents you from doing so. Also, I suggest you test it on a single Section to see how easy/hard it is to do and how convenient/awkward it is for a reader to deal with.
- Consider WHO will read the document and HOW they will read it. Some readers of the doc will only focus on one or two Sections (e.g. the Department of Fisheries might only focus on marine Sections and ignore terrestrial fauna sections), while others may read the entire document. For a reader who has a limited focus, you cannot assume that because they are reading Section 9 that they’ve read the preceding Sections 1 to 8; even for readers who read the entire document, you can’t assume that they’ve read and remembered what was said in earlier Sections.
- Please DO NOT consider converting the existing automated x-refs into manual ones. There be dragons… Future updates to the documents (e.g. insert/delete a subsection, table/figure) would mean that existing references to subsection numbers, table/figure numbers would be out of order and it would be a nightmare to try to find and fix them all. Automated x-refs mean that you can add/delete material without upsetting the links.
Ultimately, knowing who the likely reader is for this document and how they will access the document will dictate the direction my colleague will take. After all, such a document is about the reader, not the writer, so whatever is easiest for the reader to deal with should prevail over any ‘it’s too hard’ issues that the authors may have.
- Other posts from this blog related to cross-references: http://cybertext.wordpress.com/tag/cross-references/
[Links last checked October 2012]