Indexing Workshop

1. Indexing Workshop presented by Susan Self Technical Publications Department April 24, 2000

2. Overview • The purpose of an index • The typical indexing situation • A method for indexing • Concluding thoughts about indexing

3. The purpose of an index • Provides an efficient means of random access to a topic • Contains an entry for every useful nugget of information • As an editing tool, reveals: • scattering of topics • inconsistent terminology • omissions Depending on the complexity of a book, the length of a good index should be from 5% to 20% of the pages in the book. For example, a 100-page manual should have an index that is between 5 to 20 pages in length.

4. The typical indexing situation • Writers do the index last, in a hurry. • They vaguely try to imitate the indexes they have seen. • The indexes produced are too short and have too little information to be useful. • Readers do not use the indexes because they cannot find what they are looking for. • Readers call technical support for answers they cannot find in the manual.

5. A method for indexing Using an explicit indexing method can save time and produce a more useful result. Step 1: Review the manual Step 2: Make initial index entries Step 3: Edit index entries for mechanics Step 4: Edit index entries for simplicity Step 5: Assess index quality

6. A method for indexingStep 1: Review the manual • Familiarize yourself with the material thoroughly • Read the manual cover to cover • Take note of: • the terms being used • how the book is organized by topic • how various topics are related to each other

7. A method for indexingStep 2: Make initial index entries • Identify topics for entries • Named items • section headings • subjects of figures, tables, and examples • acronyms and abbreviations • functions, commands, parameters • window names, field names • menu options • Conceptual items • new and difficult concepts • main features of a product • main topics of paragraphs • main user tasks • user synonyms • information in appendixes

8. A method for indexingStep 2: Make initial index entries (cont’d) • Classify each item you identify • Put similar objects as secondary entries under a class entry: DISCO shelf cards wizards power supply card Agent Backup and Restore controller card BSM Field Migration BCNIC card Log Management ATMIC card Neighborlist • Put each such object as a primary entry in which you identify its class: BCNIC card (DISCO shelf) Agent Backup and Restore Wizard • Put variations or instances of a class as secondary entries: IMUX shelf neighbor list 5-slot in NCF 12-slot in Pilot Database

9. A method for indexingStep 2: Make initial index entries (cont’d) • Group multiple actions performed on an object: SBS shelf log template removing creating installing deleting modifying • Group multiple objects associated with an action: verifying starting system status BSM Operator Center PC software data collection rack and shelf indicators default log BSM DAT drives log manager 4-mm DAT drive modems • Put unique, unrelated items as primary entries on their own: voltage surge suppresser Xterm

10. A method for indexingStep 2: Make initial index entries (cont’d) • Use specific, low-level items only as secondary entries: agent name BTSC TCC MINI_BTSC • Use multiple levels of entries to a maximum of three: SBS shelf master shelf nonmaster shelf adding to a VBSC removing from a VBSC

11. A method for indexingStep 2: Make initial index entries (cont’d) • Use gerunds (verbs ending in “ing”) as nouns to describe important actions: testing translating E1 backhaul binary log files to ASCII format T1 backhaul path names to FDN • Use a primary entry for a noun and its acronym, expanding the acronym: Radio Base Station (RBS) RBS (Radio Base Station)

12. A method for indexingStep 2: Make initial index entries (cont’d) • If the number of secondary entries for the noun and its acronym are long, eliminate redundancy by using a see reference for the most commonly used term: Radio Base Station (RBS) see RBS RBS (Radio Base Station) 1102 1103 1106 • Derive an index entry from each section heading. Do not simply copy the text. Heading Resulting entry Power supply removal power supply removing Mouse and keyboard conventions keyboard conventions mouse conventions

13. A method for indexingStep 2: Make initial index entries (cont’d) • Use a noun or descriptive phrase to indicate a context for a term: siteName parameter ATMInterfaceCard MO -upgrade (impact option) FDL tab • Add entries for synonyms: Round Trip Delay packet data router propagation delay CISCO 4700

14. A method for indexingStep 2: Make initial index entries (cont’d) • Add entries for see or see also cross references: Neighborlist Configuration File see NCF Fully Distinguished Name (FDN) specifying a log element translating to see also FDN Translator window Put the see also entry last in the list by specifying a zzz sort order: <$nopage>Fully Distinguished Name (FDN):<italic>see also<Default Para Font> FDN Translator window[Fully Distinguished Name (FDN):zzz] • Use see and see also references sparingly as they force the reader to keep looking for information. Use a see also reference only when at least one page number is already given.

15. A method for indexingStep 2: Make initial index entries (cont’d) • Add meaningful permutations of words in primary entries: call data polling local heap storage polling call data storage, local heap heap storage, local • Avoid non-meaningful or confusing permutations: frozen, alarm function, monitoring the auto restart • Use general terms like “description,” “overview,” and “introduction” only as secondary entries. Use “description” for general information and “definition” for precise explanation of a topic. Node Manager CDSU shelf vertical neighbors description connections configuring menu functions functional description definition exiting physical description example

16. A method for indexingStep 3: Edit index entries for mechanics • Do an initial consistency check in FrameMaker: 1. Set the Find window to find Marker of Type: Index. 2. Open the Marker window. 3. Press the Find button to see the index marker contents in the Marker window. 4. Keep pressing the Find button and assess whether there are inconsistencies forindex entries within the current chapter and/or among this and other chapters. 5. Fix any problems you discover. 6. Continue this process with all chapters in the manual. • Generate the index, print it out, and mark any problem areas. • Generate an editable marker list using IXgen. 1. Using the printed index as a guide, fix the problems in the generated file. 2. Apply the changes in the generated file back to the chapter files. • As you expand and correct the index, regenerate it, print it out, mark the problem areas, and correct them in an iterative process until you are satisfied and/or exhausted!

17. A method for indexingStep 3: Edit index entries for mechanics (cont’d) • In primary entries, use singular for: • a single object or instance: demarcation panel • a single object introducing a list of actions: configuration file checking for errors creating editing • an object introducing a list of instances: antenna gain in antenna display bin query path loss calculation

18. A method for indexingStep 3: Edit index entries for mechanics (cont’d) • In primary entries, use plural for a class or a class introducing a list of related objects: partitions service options database logfile swap space • Use prepositions to clarify the relationship between a subentry and the entry above it: received power searching for a text string materials at mobile in a log file for rack installation displaying for a sector in an alarm log file list of for subscriber location from all sectors • If all subentries begin with the same preposition, you can move the preposition to the header: searching for a text string in log file alarm log file

19. A method for indexingStep 3: Edit index entries for mechanics (cont’d) • Use prepositions rather than conjunctions to show relationship: temporal analysis data temporal analysis data and MO hierarchy MO hierarchy, modifying in and web interface in web interface • Do not begin index entries with definite or indefinite articles: resetting resetting an RF Chain FER counters FER counters RBS site the RBS site RF Chain • Put in multiple entries for phrases that begin with a numeric character: IMUX device 12-slot IMUX device 12-slot 5-slot IMUX device 5-slot

20. A method for indexingStep 3: Edit index entries for mechanics (cont’d) • Show page numbers only at the lowest level: synch channel channel weight 3-26 data rate default 6-48 setting 6-28 power at each sector 3-27 To prevent displaying a page number for a header, use the header only with a subentry: synch channel:channel weight data rate:default data rate:setting • Use the <$nopage> tag to suppress page numbers for see and see also references: shell see RBS shell <$nopage>shell <italic>see<Default Para Font> RBS shell

21. A method for indexingStep 3: Edit index entries for mechanics (cont’d) • Be consistent in capitalization. • Use lower case for common nouns, gerunds, and UNIX commands: consolidation bus arbitration debug log troubleshooting the backhaul migrating the BSM database bsmmanagemodems script rtd command • Use initial caps for proper nouns and products: Cisco Catalyst 5000 MIB Call Summary Display window CSU rack fan tray assembly FDN Translator FASE Alarm Backhaul Interface Module (BIM) • Resolve different word forms into one form and be consistent: Round Trip Delay measurement Round-Trip Delay measurement Round Trip Delay (RTD) measurement Round Trip Delay (RTD) measurement round-trip delay measurement round trip delay measurement

22. A method for indexingStep 3: Edit index entries for mechanics (cont’d) • Use font changes to indicate the character of words. • Use the <code> character tag for UNIX tools, commands, options, parameters, variables, code words, and file names: impact tool hardwaretype parameter options agentping command -check environment variables -config LM_License_File PRINTSERVER GPSdata.dat <code>impact<Default Para Font> tool:options:<code>-check<Default Para Font> • Use the <italic> character tag for see and see also references. web interface see RBS Web Interface <$nopage>web interface <italic>see<Default Para Font> RBS Web Interface alarms see also defects <$nopage>alarms:<italic>see also<Default Para Font> defects[alarms:zzz]

23. A method for indexingStep 4: Edit index entries for simplicity • Strive to have no more than two page references per index entry. Create logical subentries that are more helpful to readers. loopback plug 7-9, 7-22, 7-30 loopback plug 7-43, 8-14, 9-1, 9-4 building T1 circuits 7-9 building fractional T1 circuits 7-22 building E1 circuits 7-30 building fractional E1 circuits 7-43 E1 backhaul test equipment list 8-14 Telco backhaul test equipment list 9-1 troubleshooting the Telco backhaul 9-4 debug log 2-20, 2-26, 2-59 debug log changing debug flags 2-20 setting default parameters 2-26 viewing 2-59

24. A method for indexingStep 4: Edit index entries for simplicity (cont’d) • Keep primary entries as simple as possible. Do not use commas or dashes to indicate subentries. Use subentries instead: node, adding node node, opening and closing adding node, clearing clearing closing opening E1--Data Port 1 E1 E1--Data Port 2 Data Port 1 E1--Net Port 1 Data Port 2 E1--Net Port 2 Net Port 1 Net Port 2 fault monitoring of mirror drive system monitoring the mirror drive system for UCP-based system mirror drive system

25. A method for indexingStep 4: Edit index entries for simplicity (cont’d) • If a primary entry has no subentries and uses a comma, eliminate the qualifying information and the comma: system status board, updating system status board • If a primary entry has only one subentry, consolidate the two into one or more primary entries: log events displaying log events displaying log events Consolidate such entries only when you are done expanding the index and you know that other entries will not appear if you compile a master index. • Expand the index and improve readability. • Use subentries as primary entries. • Create additional entries by rearranging the word order of existing entries. • Include more synonyms for terms and concepts.

26. A method for indexingStep 5: Assess index quality • Use one or more of the checklists provided in the Indexing Guidelines document handed out. • Put the index aside for a few days and come back to it with fresh eyes. • Do some usability testing: 1. Give the index and the manual to TAC, training, system test, peer reviewers, or other groups. 2. Ask them to try to locate topics in the manual just by using the index. Have them develop a list of terms that they would be interested in looking up and then see if the index has them. This could be made into a fun and illuminating game. 3. Ask the testers to provide feedback on whether they could find the information they were looking for. Ask for suggestions for improvement.

27. Concluding thoughts about indexes • Developing an index requires a lot of work in the same way as writing a manual from scratch. • Once developed on a good foundation, an index can grow and evolve and become richer and more useful. • When you have a good index, readers feel more control over a manual because they have a quicker, more random access into the topics they need to know about immediately. • A good index enables you to find topics in your own manual more quickly. Becoming a user of your own index tells you honestly how complete or inadequate your index may be. • Strive to make indexes that you find useful but realize that there is no such thing as a perfect index. Accept the level of completeness that you can achieve within your time limits.