Indexing advice

[Susannah Skyer <susannah -at- SCO -dot- COM>]

Here's an article on indexing from our in-house style guide.
Some of this is pretty SCO-specific, but other bits may
be of interest.

Enjoy,

Susannah Skyer
Unix Doc Project Lead
SCO EMEA (Europe, Middle East, Africa)
---------------------------------------------------------------------
 Indexing

    Indexes are among the most important parts of any documentation.  Very
    few users read documentation from beginning to end.  Most read the
    sections they must, and rely heavily on indexes for needed guidance.
    Consequently, the index must be very carefully and completely
    constructed.

    When creating an index, consider:

    +  what terms to index

    +  how to word each entry

    +  where to insert each entry in the text

    +  which synonyms to use

    +  where to use page ranges

    When you are creating and reviewing your index, keep the reader's needs
    foremost.

    First, recognize that an index can have a very diverse set of readers,
    depending both upon the type of guide and the level of experience of the
    users.  Therefore, your index needs to include terminology and synonyms
    that respond to the needs of all users, from the novice to the expert.
    Ask reviewers and users to help you come up with appropriate terms.

    Check the index.nouns and index.verbs files in the dochelp directory and
    take from them what you can.  If you have suggestions for new entries in
    those files, please send them to your site editor.

    Remember the importance of including keywords, commands, menu options,
    glossary terms and so on.  For assistance, look at your section headings
    and use them to create appropriate index entries.

    Finally, try to be concise in the wording of entries.  The goal is to
    point readers to the desired information, not to outline it.

 Steps in creating an index

    The process for creating an effective index generally consists of the
    following steps:

    1.  Writers create index entries and generate a preliminary index.

    2.  Writers gather tech review comments on the indexes, edit the entries,
        and generate a revised index.

    3.  Editors evaluate and edit indexes both technically and stylistically.

    4.  Writers incorporate editorial revisions and format indexes for
        typesetting.

    Several iterations of the first three steps may be necessary in this pro-
    cess.

 Style conventions

    Our basic style conventions require:

    +  In main entries, capitalize the first letter of the first word and
       proper nouns.  Entries not capitalized include:

       -  command names (which should be immediately followed by their
          manpage section reference, for example: tar(C).  You will need to
          manually reduce the section letter point size with s-1.)

       -  filenames

       -  routine names

       -  any others where altering the case may create ambiguity or
          confusion

    +  In subentries, capitalize only proper nouns.

    +  In page ranges, use the BEGIN and END arguments to the .XX macro. If
       you see:

          Entry, 1,2,3,4,5,6,7

       and the text is actually a continuous discussion,  repeated .XX
       entries have been used, and these should be changed to a single
       BEGIN/END pair.  See the sco.mac User's Guide for more information.

    +  Avoid index entries that break over more than one line. As a general
       guideline, limit entries (including subentries, but not page numbers)
       to 35 characters, when possible.

    +  Make sure that the spelling and capitalization of the entries is
       consistent.  First check the style guide's vocabulary list; if the
       word in question is not listed there, use the first (preferred)
       spelling in the current Webster's New Collegiate Dictionary.  Ask your
       site editor if further clarification is required.

    +  Expand acronyms only when this aids access.  If expanded, an acronym
       should only be expanded in the main entry (not repeated in the
       subentries).

    The following style guidelines are automatically enforced by the sco.mac
    and mkindex tools and should only require spot checking:

    +  alphabetization

       -  special characters appear at the beginning of the alphabet by
          default, although this is configurable; see the sco.mac guide.

       -  when / (slash), \ (back slash), and . (period) are used to indicate
          filenames, macros, or other special uses, they are ignored in
          alphabetizing and filed according to the succeeding letter.

    +  hyphenation

    +  italics on See and See also

    +  indentation of subentries


 Questions for reviewing an index

    The following list is designed to provide a starting place for reviewing
    an index.

    +  Are there missing entries?  Have all important subjects been covered?
       For assistance, turn to the table of contents and check to see that
       the titles are represented in the index.  You should also do a random
       check throughout the document, further ensuring that the subjects are
       incorporated properly into the index.

    +  Are entries logical and meaningful?  That is:

       -  Would a reader look under this entry for the subject?

       -  Does the entry use the same language as the text (that is, in terms
          of punctuation, capitalization, spelling, and wording)?

       -  Are entries consistent with index.* files (in your local dochelp
          directory)? If an author's original wording varies from the index.*
          files, the term should be indexed under both wordings.  (If this
          produces a sloppy looking index, for example, near-identical terms
          one after another, editorial discretion may be used.)

    +  Are the entries in noun form whenever possible? Gerund forms should be
       limited to qualifying terms and subentries wherever possible.

       For example:

          Changing colors

       should be:

          Colors, changing

       and

          Creating portable data with XDR

       should be:

          XDR, portable data creation

       or perhaps:

          XDR, creating portable data

       The goal here (and with the following guideline on bringing keywords
       forward) is to use the clearest term possible as the first-level
       entry.

    +  Are inversions done correctly, bringing key words forward?  For
       instance, consider the following example from development system doc:

          Data structures, x.out symbol table

       An improvement would be simply:

          x.out symbol table

       Otherwise, the specific and useful entity is hidden behind a general
       and (in indexing terms) useless one.

    +  Are the inversions useful?  For example, if you have in your index:

          Authentication, service dispatch routine

       you may not want to invert this, placing ``service dispatch routine''
       first, because you believe ``Authentication'' is a more useful
       keyword.  However, a good rule in these cases is to index under both
       forms to provide greater keyword access; that is, list both:

          Authentication, service dispatch routine

       and

          Service dispatch routine authentication


    +  Do subentries have a logical relationship to main entries?  Does every
       subentry make sense under its main entry?  (This is a point you would
       want to ask subject matter experts to review.)

       For example, do the following subentries all make sense under
       ``Mode''?:

          Mode
            changing
            single user
            system maintenance

       One way of clarifying this example would be:

          Mode
            see also chmod(C)
            file, changing
            system (init level), changing
          Single-user mode
          System maintenance.  See Single-user mode


    +  Is the wording of subentries consistent, both for subentries under the
       same main entry and for all main entry/subentries groups throughout an
       index? For example, the following subentries could be reworked
       slightly so that gerund forms were used throughout:

          Button binding
            configuring
            context
            creating
            event definitions
            specifying resources

       One revision might be:

          Button binding
            configuring
            context
            creating
            events, defining
            resource, specifying

       Once you have creating a set of subentries for one entry, similar main
       entries should have  similar subentries.  For example, the following
       listings of serial communication topics could be improved by using
       similar (if not identical) terminology in the subentries.

          cu(C)
            dialing out
            login sequence
            modem connection errors
            troubleshooting modem
          UUCP
            dialer program
            error messages
            login
            modem
            problems


    +  Are main entries containing many page locators broken down into
       subentries?

       A rule of thumb from the Chicago Manual is that main entries with more
       than five or six page references should be broken into subentries.

    +  Are there subentries with the same page locators under the same main
       entry?  If so, combine the entry and the subentries.

    +  Are main entries with many subentries regrouped into main entries?

       If there are a large number of subentries under one main entry, the
       subentries should be regrouped. The following example would be far
       more usable with less subentries.  This could be achieved by
       eliminating similar subentries and promoting the most important
       subentries to main entries:

       Modems
         auto-answer
         baud rate
         checking baud rate
         checking /etc/gettydefs files
         checking modem cable
         configuring
         connecting
         data compression
         dialers
         Dialers file
         dial-in
         dialing configuration
         dial-out
         editing /etc/inittab
         error correction
         Hayes (and compatible)
         incompatible
         installing
         local network switch
         login sequence
         null modem
         pin connections, cabling
         planning
         printer
         printer connection
         problems in UUCP
         speed conversion
         supported
         switch settings
         telephone line
         testing
         testing phone line
         Trailblazer
         troubleshooting
         UUCP use
         volume

       Another option is to introduce subsubentries (third-level entries).
       Generally, this is discouraged, because it adds complexity to the
       index, but in dire cases, such as the example above, third-level
       entries could be an improvement.

       In some cases of excessively long lists of second-level entries under
       a particular first-level entry (as in listing every UNIX command under
       'command'), you may want to produce a glossary of commands and insert:

          .SX "Commands.  See Glossary of commands, page 321"


    +  Does each main entry have two or more subentries?

       If there is only one subentry, combine the subentry with the main
       entry.

    +  Are entries appropriately specific (that is, neither too general nor
       too detailed)?

    +  Are cross-references used correctly?  That is:

       -  Look for (and eliminate) cross-references that lead nowhere.

       -  Do not refer a user to another entry that includes less than three
          page locators.  In those cases, just double post.

       -  Ensure that all cross-references provide additional information.

       -  Evaluate again whether there are any missing entries.

       _________________________________________________________________________
          NOTE  Except for cases where an urgent fix is required, writers
          should edit their index entries in the troff source files
          instead of the formatted index file.  This ensures that the fix
          is incorporated when subsequent indexes are generated.

          In this event, the source file should be opened again and the
          index entry modified once the urgent work is done, so that a
          reprocessed index will duplicate the index urgent fix.
       _________________________________________________________________________


 Technical review and usability testing

    Proposed index entries should be technically reviewed alongside the
    document they index. Ask reviewers to comment on the terms you already
    have - would the reader search under these terms?  Also (and you may want
    to do this before you've shown the reviewers your list of terms), ask
    them to brainstorm terms that should be indexed.

    You can work this into a kind of usability test by asking a spectrum of
    reviewers (find those representative of your audience if possible) to:

    +  review a small chunk of new doc (highlight what's new)

    +  note which terms from their review doc they believe should be indexed

    +  look in the index of the doc and see if their terms were there

    +  note ``hits'' and ``misses'' on form

    Another type of usability testing you can do is:

    +  pull random passages from your doc (you can write an awk script or
       other program to do this) - these passages should contain no headings,
       page numbers, or other locators

    +  give testers some random passages, plus a complete index, plus a
       complete book (containing all random passages, but in their real
       order, with headings and page numbers)

    +  monitor the testers as they attempt to locate the random passages in
       the index; ask them to think out loud as they do

    +  record their ``hits'' and ``misses,'' along with any other information
       that will help you to improve the index.

    (These usability tests were presented by Deborah Swain of IBM at 1993
    Society for Technical Communication conference.)

 See also


    +  Docsplit

    +  .err files

    +  sco.mac code

    +  sco.mac User's Guide

    +  the indexing chapter in the Chicago Manual of Style

    +  IBM's Information Development Guideline: Indexing (available from your
       local indexing team member)

    +  Proposed American National Standard Guidelines for Indexes for Infor-
       mation Retrieval (available from your local indexing team member)