Cross-references

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.

See also:

• Other posts from this blog related to cross-references: http://cybertext.wordpress.com/tag/cross-references/

[Links last checked October 2012]

Word: Sometimes a List of Tables/Figures just won’t update

I’ve had several documents recently where the List of Tables and/or List of Figures just won’t update to list all tables/figures in the document.

The captions are all applied correctly, and I’ve tried the various methods for updating the fields. I’ve even reinserted the List of Tables/Figures — all to no avail. Some tables/figures just don’t show in the lists.

I’ve suspected it was to do with track changes being on in the document, even though none of the captions or the paragraphs surrounding them were the subject of tracked changes. And I also suspected that something was happening with the field updating that can get messed up when track changes are on (see http://cybertext.wordpress.com/2009/10/16/word-macro-to-fix-track-changescross-references-issues/ for how to fix that).

To confirm my suspicions, I copied a document that wouldn’t behave and put it into a testing area (so I wouldn’t mess up the original). I then accepted all track changes in the document and updated the List of Tables. It worked! All the tables that should have been listed originally were now listed correctly.

The problem is that the authors need to keep on track changes so that the regulators can see what’s changed in these docs, so they have three choices:

• Accept all track changes (NOT an option for these docs)
• Ignore the pesky List of Tables and hope that the reader doesn’t notice ;-)
• Ignore the pesky List of Tables and make a note to the regulators that it will update correctly once all track changes are dealt with.

[Links last checked March 2012]

Message to Microsoft: Fix Word’s cross-reference dialog box. Please.

I use Microsoft Word — a lot. I’ve been using Word since the heady days of Word 2.0, and I’ve been using Word 2003 and more recently Word 2007 day in/day out for the past two years on my current contract. I’ve been getting up close and personal with Word, as evidenced by the number of blog posts I’ve written on Word’s idiosyncrasies. While there have been many improvements in Word 2007, there are areas that still have a way to go.

Most of the documents I’ve been working on for the past two years are long scientific reports — a single document can have hundreds of cross-references to figures, tables, plates, sections, appendices etc.

As a result I’ve opened the Cross-reference dialog box more times than I can count. And that dialog box alone sucks as far as usability is concerned (‘sucks’ is a technical term!). While there have been some improvements to this dialog box in Word 2007, there’s a lot about this dialog box that just doesn’t work efficiently. (NOTE: I have not used Word 2010 yet, so these comments are about Word 2007. I’d appreciate it if someone using Word 2010 can report if any of these issues have been fixed.)

So, if you’re listening Microsoft, here are 10 productivity improvements I’d like to see made to this dialog box (numbers are used for reference only — they do not imply priority or sequential order):

1. Remember dialog box resizing. In Word 2007, this dialog box is resizable (yay!). But don’t get too excited… When you close the dialog, the size you’ve dragged it to is not ‘remembered’, so as soon as you re-open the dialog, it’s back to its default size and you have to resize it again. This gets ‘old’ very quickly. Yes, I know I can keep the dialog box open while I’m doing other things in the document, but sometimes I need the screen real estate and so I’ll close it only to re-open it again a few minutes later, and have to resize it again.
2. Resize the drop-down selection lists to fit the available selections. The current situation is just bad design, in my opinion. Even the default Reference type list includes more selections than are visible in the drop-down list. And if you’ve added more (e.g. Plate, Equation, Photograph), then the list is even longer. But someone, somewhere at Microsoft decided that this drop-down list would only ever display 6 items! Which means if you have a list longer than that, you have to scroll. Oh, and for bonus points, someone at Microsoft decided not to list these selection options in alphabetical order!
3. Increase the number of items displayed by default. The default size of the dialog box only displays 12 items in the list of available headings, figures, tables etc. Long documents can easily have hundreds of headings. If there are only a few items in a particular document, then keep the default at 12, but if there are many more than 12, make the default something like 30 items. Surely a simple if/then statement in the code could make this possible? Of course, if Word remembered the dimensions of my resized dialog box (see item 1 above), this point about the default number would become moot.
   
4. Give me the option to expand/collapse headings. As mentioned in item 3 above, a long document can have hundreds of headings. Some documents I’ve worked on have 30+ subheadings (at various levels) within a major heading. If I need to set a ‘heading’ cross-reference to section 8.2.3.5, then I really don’t want to scroll through every heading in sections 1, 2, 3, 4, 5, 6, and 7 as I do now. Yes, I know I can type the first character of the heading I want and skip to the beginning of that section quickly (e.g. type 8 to go to the 8.x headings if using an outline numbered list), but I still have to scroll to get further down to section 8.2.3.5. If this list had expand/collapse functionality, then I could collapse all headings I didn’t want to see and just expand the section I was cross-referencing. Of course, ‘collapse all’/'expand all’ options should be available too. By the way, typing the first character only works effectively in the Heading and Numbered Item lists; however, if your table and figure lists start with the words Table or Figure, then typing a number or letter does nothing, and you have to scroll.
5. Hide Reference Types not used in the document. This one is related to item 2 above. The documents I’ve been working on don’t use footnotes or endnotes, yet these are listed in the Reference type list. Why? If the document doesn’t use them, then they shouldn’t be available for selection. If I want to reference something in another document, then I can’t do it via this dialog box anyway.
6. Remember my ‘Insert reference to’ preference for each Reference Type. This one is REALLY annoying. Because I switch between inserting cross-references to figures, tables, sections etc. within a section of text, I’d like Word to remember my Insert reference topreference FOR EACH TYPE while I’m in the current session. It can forget my preferences after I close Word, but while I’m working I’d like it to remember each insert preference for each Reference Type. Let me give you an example of how it works now:
   1. I select Table as my Reference type, then Heading number (no context) as my Insert preference, then I select the table.
   2. Let’s say the next item I have to insert a cross-reference to is another table. I can leave the dialog open, select another table and the Heading number (no context) selection also applied. So far, so good.
   3. The next cross-reference is a Figure, so I select Figure as my Reference type, then Heading number (no context) as my Insert preference, then I select the figure.
   4. Now I have to cross-reference another table. You’d think that Word would remember my previous table insert preference, but it doesn’t. I have to select Table and Heading number (no context) as my Insert preference AGAIN.
   5. And if the next one is a figure, I have to repeat that.
   6. Repeat for all the other Reference type/insert combinations. With potentially hundreds of cross-references in a single document, and hundreds of documents, this one gets old real fast.
7. Let me set default Reference type/Insert combinations. Perhaps a better option than ‘remembering’ my most recently used Reference Type/Insert combination (see item 6 above) would be a setting where I could set my default Insert preferences for each Reference Type — that way, I could set it up once and not have to bother with it again. I’d still have the option for changing the insert options for an individual cross-reference, but the defaults would apply otherwise. This setting could go under Word Options > Display settings, or Word Options > Advanced where everything else seems to get dumped.
8. Provide an option to list Level 1 paragraph styles in the Heading list. My client uses a special style for Appendix headings. This style has its Outline Level paragraph setting set to Level 1 so that it gets picked up and displayed in the automatic Table of Contents. However, these appendices do not use a standard Heading 1 to 9 style so are not listed in the Reference Type list for Heading — to find the appendices, I have to select Numbered Item and scroll to the bottom of that list. The writers on my team are scientists, not Word experts — they invariably cannot find the appendices when inserting cross-references, so they have to ask me to fix them.
9. Let me assign ‘preserve formatting’ to the inserted cross-reference field from within this dialog box. Occasionally, and for no reason I can discover, the ‘preserve formatting’ option for an inserted cross-reference field goes missing. I don’t know whether it’s on insertion or something that an author does with it later (which is hard to believe as most of the authors I’m dealing with have no clue that these are fields, let alone how to fiddle with them). So a check box on this dialog to ‘preserve formatting’ might be useful as long as it didn’t mess up anything else with these fields (like become a toggle switch).
10. Provide a double-click option to insert the cross-reference. When I find the correct table, figure, section cross-reference etc. to insert, I have to select it from the list, then click Insert; or select it then press the Tab key to go to the Insert button, then press Enter; or select it and press Enter. Another option I’d like for inserting a cross-reference is the ability to double-click the selection. With the existing options, you have to select the item (usually with the mouse), then do another one or two different actions (press a key, move and click the mouse) before you get the selection inserted. With a double-click option, double-clicking a selection would save mouse movements and prevent you having to switch from mouse to keyboard etc.

As I mentioned in my earlier blog post about the annoyances on this dialog box, these things would probably not bother someone doing the occasional insertion of a cross-reference. But for writers and editors working with long documents, reports, proposals, etc. who have to insert many cross-references, streamlining the functions of this dialog box would save many mouse movements and a LOT of frustration.

Does anyone know how to make suggestions to Microsoft? There used to be a ‘wish list’ address that was monitored, but I no longer know what that email or web address is, nor whether suggestions such as those above even get considered. If you know how to contact Microsoft, please comment below.

[Links last checked August 2010]

Word: Remove formatting from cross-references

Sometimes you’ll add a cross-reference to a figure or table, and part of it (the number usually) will display in bold text. Or perhaps you’ve inserted the cross-reference in a table but the font used in the table is smaller than that used in the body text, yet the cross-reference displays in the larger font.

I’m not sure what causes it but here’s how to fix it:

1. Right-click on the cross-reference field, and select Edit Field.
   
2. The Preserve formatting during updates check box should be checked — check it if it’s not, then click OK.
   
3. Select the cross-reference field, and manually change the formatting to what you want it to be (remove the bold, make the font smaller or larger, or whatever formatting is ‘out of whack’). It should now hold for any future updates of that field. You can test it by updating the field.

(Hint: If you use fields a lot and need to know where they are in your document, turn on the option to always show them shaded in gray.)

See also:

• Bookmark cross-reference formatting (when preserve formatting doesn’t seem to work): http://cybertext.wordpress.com/2008/12/22/word-bookmark-cross-reference-formatting/
• Unbolded caption numbers: http://cybertext.wordpress.com/2010/08/02/word-unbolded-caption-numbers/ ‎

[Links last checked February 2012]

Word: Macro to fix Track Changes/Cross References issues and accept all field changes

The problem

When all Track Changes have not been accepted, you may not be able to insert a cross-reference to a table or figure caption correctly. Either you see multiple instances of the caption listed in the Cross Reference dialog box, OR you don’t see the caption at all, OR you see an incorrect table/figure number for the caption (e.g. you see Table 5.1 instead of Table 1.1).

This is a known issue with Word since at least Word 2000 (see the list of resources at the end of this post).

The issue

You’d think that accepting all changes would be sufficient. And it is. But accepting all changes is not appropriate where you have a document that MUST keep Track Changes on, such as one that has to go through a regulatory compliance process through all its revisions. I have been working on these types of documents. In Word 2003, it was never really an issue – double-upped cross-references were an annoyance more than anything, and we never noticed any that were missing. But as soon as my client started using Word 2007, we came across serious issues with existing table and figure captions not being listed in the Cross Reference dialog.

A little testing showed that it was related to Track Changes being on and the acceptance of all changes in the document. Armed with that knowledge, I headed off to trusty Google to try to find a solution — a solution that allowed cross-reference and caption fields (and lists of tables and figures) to be updated without affecting other parts of the document.

Solution

Macropod (clever name!), a Microsoft Word MVP, had posted a macro that solved the problem (http://www.pcreview.co.uk/forums/thread-31716892.php). It worked great, but it dropped me into the footer and into Draft view at the end of the document when it was finished. So I posted my request to the Microsoft Word Programming Discussion Group, and the ever-helpful Macropod tweaked his/her original macro to get me what I wanted, which was to return to where I was when I ran the the macro.

Here’s Macropod’s revised macro:

Sub AcceptTrackedFields()
Dim oRng As Range ' All Range objects - includes ranges in the body, Headers , Footers & Shapes
Dim Fld As Field ' Field Object
Dim oView As Variant ' The original document view
Dim SelRng As Range ' The original selection
' Turn Off Screen Updating
Application.ScreenUpdating = False
With ActiveDocument
oView = ActiveWindow.View.Type
Set SelRng = Selection.Range
' Loop through all range objects and accept tracked changes on fields
For Each oRng In .StoryRanges
Do
For Each Fld In oRng.Fields
Fld.Select
Selection.Range.Revisions.AcceptAll
Next
Set oRng = oRng.NextStoryRange
Loop Until oRng Is Nothing
Next
End With
With ActiveWindow
If .View.SplitSpecial = wdPaneNone Then
.ActivePane.View.Type = wdPrintView
Else
.View.Type = wdPrintView
End If
.View.SeekView = wdSeekMainDocument
.View.Type = oView
SelRng.Select
End With
' Restore Screen Updating
Application.ScreenUpdating = True
End Sub

Thanks heaps, Macropod! The generosity of the Microsoft MVPs and community is humbling.

See also:

• How and where to store this macro so that you can use it with all your Word documents: http://cybertext.wordpress.com/2009/10/18/word-separate-out-macros-and-attach-them-to-all-documents/

Some websites that discuss this issue

• http://www.tech-archive.net/Archive/Word/microsoft.public.word.docmanagement/2008-12/msg02350.html (or http://bit.ly/zY0fh)
• http://www.tech-archive.net/Archive/Word/microsoft.public.word.docmanagement/2008-12/msg02346.html (or http://bit.ly/3RsWxT)
• http://www.shaunakelly.com/word/trackchanges/HowTrackChangesWorks.html (question and answer near the bottom of this page)
• http://www.pcreview.co.uk/forums/thread-3715892.php (macro solution)
• http://robsnotebook.com/ms-word-track-changes-printing-crossrefs
• http://support.microsoft.com/kb/252619 (shows that it was an issue back in Word 2000!!)
• http://www.mcse.ms/archive/index.php/t-2809819.html (option to lock fields??)
• More on locking the fields: http://wordribbon.tips.net/Pages/T009921_Stopping_Automatic_Changes_from_Being_Tracked.html

See also:

• List of tables/figures won’t update: http://cybertext.wordpress.com/2012/03/28/word-sometimes-a-list-of-tablesfigures-just-wont-update/

[Links last checked October 2009]

Word annoyance: Cross-referencing

Sometimes I wonder if Microsoft employees have ever used Word for a long document with multiple heading levels, hundreds of headings, figures and tables, and lots of cross-references to those headings, figures and tables. My experience with Word would suggest not. (I did hear that Microsoft employees use an internal XML system for their documentation, which if true, gives lie to ‘eating your own dog food!’)

So what’s my peeve this time? The Word 2003 Cross-reference dialog box (and, to an extent, the Word 2007 Cross-reference dialog box, though some things have been fixed).

What’s so annoying about it? Well, it just DOESN’T work well with long documents where you have to insert many cross-references. I’ve been working on hundreds of these types of documents since last September and there are some simple things that could improve the experience for those of us who have to use this function many times a day.

Here’s the Word 2003 dialog box, showing that there are many many headings in this document — the vertical scroll bar on the right indicates that Section 5.6 in this example is only about a quarter of the way into this document.

Word 2003 Cross reference dialog box

So how is this Word 2003 dialog box broken?

• You cannot resize the dialog box any which way, which means that you have to continually scroll the list nine items at a time (Home and End work within it as do the page up/down keys, so that helps a little). This is sort of fixed in Word 2007 — the dialog is resizable for both height and width, but the resizing does not hold if you close the dialog box. As soon as you re-open it, it goes back to the default size.
  
• The heading levels cannot be collapsed — they always open fully expanded, which makes it painful to get to Section 12 of 24 sections, for example. Again, you have to scroll to get there. This is the same in Word 2007. Surely it would be a simple thing to add expand/collapse icons for the Headings list??
• If you select an item, then click Insert and leave the dialog open, then select another item and click Insert again, the next time you try to do this, you lose the scroll bar and end up at the top of the list. Now you either have to close the dialog and start again, or use the page up/down etc. keys to navigate to the next cross-reference (the scroll bar is inactive) OR — here’s a tip — click in the scroll bar BEFORE you select the second and subsequent items, then you won’t lose it. It’s an extra click but quicker than having to scroll using the keyboard or closing and re-opening the dialog box. This appears to be fixed in Word 2007, based on the little testing I did.
• The Insert reference to option does not hold between various Reference types. For example, if I choose Only label and number for a Figure, then I insert some figure cross-references, everything is fine. But if I then insert switch reference type to a Table (perhaps also selecting Only label and number) then when I go back to inserting a Figure cross-reference, the default (Entire Caption) is displayed and I have to re-select Only label and number, even if I’m in the same session (i.e. I haven’t closed the dialog and I haven’t closed the Word document). What I would like is for the selection I made the last time I inserted a Figure in this session to hold for the next time I insert a Figure. This would save me hundreds of mouse clicks per document! This is not fixed in Word 2007, which exhibits the same behavior as Word 2003.

These are all little things that perhaps wouldn’t be noticed if you were only using this dialog occasionally. But I’ve had to open it and insert thousands of cross-references over the past six months or so, and it’s limitations are apparent. And annoying.

See also:

• 10 suggestions to fix the Cross Reference window: http://cybertext.wordpress.com/2010/08/16/message-to-microsoft-fix-words-cross-reference-dialog-box/#comment-9175

Word: Cross-reference goes onto next page

Here’s a curly one! My client had a problem: a cross-reference to a bookmark for an Appendix was adding a page break within the body text. I’ve had these before — quite often just recreating the cross-reference will solve it. But not this time. So it was time to do some investigating…

First, I turned on the ‘show bookmarks’ option so I could see them all:

• Word 2003: Tools > Options > View tab, Show group, Bookmarks check box.
• Word 2007: Office button ,  click Word Options then Advanced on the left. Scroll down to the Show document content section, and select the Show bookmarks check box.

Bookmarks check box in Word 2003

Show Bookmarks check box in Word 2007

Next, I hunted down the bookmark for the Appendix that had its cross-reference going haywire.

This is what I expected to see — notice how the bookmarked text is surrounded by gray square brackets; this is how it should be:

How a Bookmark should look

However, that’s not what I saw. Instead I saw this:

Bookmark spanning a page break

Notice how the start of the bookmarked text (1) is just before the forced page break, and the end (2) is where it should be.

No wonder the page break was being dumped into the body of the document whenever a cross-reference for this appendix was inserted! It was being picked up with the text as Word (logically) understood it to be part of the text.

The solution was to select the correct text (i.e. WITHOUT the page break) and re-assign the AppendixD bookmark to it. Once I’d updated the document fields (Ctrl+A, then F9), everything worked fine!

Word: Bookmark cross-reference formatting

Lately I’ve been working with a colleague on some long documents with lots of Appendices etc. We’ve been using Word’s Bookmark feature to select the first part of the appendix title (e.g. ‘Appendix B’) and add it as a bookmark (‘AppendixB’).

When we need to cross-reference the appendix in the main text, we select the name from the list of bookmarks and insert it. Most times the cross-reference goes in as it should—formatted the same as the surrounding text.

But on the odd occasion and for no apparent reason, the cross-reference decides to display the formatting of the original appendix heading. I’ve put two of these suckers into the same sentence—one will go in OK and take the formatting of the surrounding sentence; the other displays in the formatting of the appendix heading (all caps and 14 pt bold!).

I’ve checked and double-checked the Edit Field and Toggle Field Code options to see if there’s anything different between the two. Nope. They are exactly the same. If I manually format the incorrect one, when I update the fields using F9, it goes back to 14 pt bold all caps. Grrrrr…

So today I’d had enough! I found out how to fix it, and I’m hoping this fix will hold for all future field code updates (it’s held the few times I’ve updated the doc today, so here’s hoping…)

Here’s what you do in Word 2003 (Word 2007 should be similar once you get to the Field window):

1. Right-click on the cross-reference text.
2. Select Edit Field.
3. On the Field window, click the Field Codes button (lower left).
4. Add a space after the \h part, then type \* charformat
5. Make sure that the Preserve formatting during updates check box is clear.
6. Click OK.

You could add this \* charformat part into the toggled field code instead, but there’s more chance of making a mistake.

Fixing formatting in a cross-reference

(I found the answer here: http://tinyurl.com/67oabt [Lockergnome site])

See also:

• Unbolded caption numbers: http://cybertext.wordpress.com/2010/08/02/word-unbolded-caption-numbers/ ‎
• Remove formatting from cross-references: http://cybertext.wordpress.com/2010/03/12/word-remove-formatting-from-cross-references/

[Links last checked February 2012]

Indexes v. full text searches

Comment from an email discussion list member

In my opinion, indexing is pointless. Searching is much more important than indexing.

I think you should provide the simplest automatic indexing, based on topic headings, and rely on your users to use full-text search to actually find anything.

Full-text search is easy and it works perfectly. Indexing, on the other hand, depends on the skill and commitment of the indexer. For myself, I feel that my life is too short to spend much of it on indexing.

My response

Yes, full text search (FTS) has its place (and Google et al have a lot to answer for in this regard).

BUT FTS brings with it a lot of garbage as it find any matching words without any reference to their context. You can narrow the results list by judicious use of Boolean operands and syntax such as quote marks, parentheses and the like—but most users don’t know about them or how to use them. However, this still doesn’t put the words into context. In many ways FTS is like a concordance… ‘let’s list every word we find in the document no matter how important it is’. Concordances treat every word equally.

Indexes on the other hand—at least, well-constructed indexes—serve a different purpose in focusing the user’s attention on the words most likely to have relevance.

Well-constructed indexes are done by humans who can detect nuances and meaning of words—in the context of their usage. Indexes created by software (of any kind) just don’t have this sophistication at the moment. A good indexer can create “see” references from unused terms to used terms, and “see also” references to similar terms. Complex indexes also refer users to broader and narrower terms.

Others have mentioned synonyms and they are one of the prime reasons why human indexers are much better at this than software. A FTS can’t distinguish between words such as “editing”, “amending”, “changing”, altering”, “modifying” (and their variations)—yet they could all be used in the document. A human indexer can set one term as the preferred term and refer all other uses to that term, thus offering the user the FULL range of topics that cover anything to do with changing something.

Others have also mentioned that print output (NOT screen versions of print, like PDF) doesn’t have FTS, and a good TOC and Index is the way users access the information. I believe there is a place for both… and I would be very sad to see the day when indexes are relegated to the trash.

See/See also: And the difference is?

If you’re unsure of the differences between a see and a see also cross-reference in an index, here’s an explanation that may help:

• See: Refers you from an unused term to a used term. For example, ‘ornithology, see birds’ means that anything about birds in this document is listed under birds in the index, not under the more scientific term of ornithology. In the index, only birds has a page number reference.
• See also: Refers you to other used terms related to this one. These terms may be ‘siblings’ or ‘children’ of the parent term. For example, you may see ‘birds, see also reptiles’. Both terms are at an equal level, so are ‘siblings. However, ‘birds, see also eagles, flamingos, parakeets’ refer to terms that are narrower than the parent term birds, so are ‘child’ terms. All terms are listed in the index with their respective page number references.

[This article was first published in the September 2005 CyberText Newsletter.]