Designing Indexes and Glossaries ITSW 1410 Presentation Media

Designing Indexes and Glossaries ITSW 1410 Presentation Media Software Instructor: Glenda H. Easter Designing Indexes and Gloossaries, Chapter 15

Differences in an Index and a Glossary þ An Index: Tells you the location Can be similar to a dictionary þ A Glossary: Defines terms and concepts Lists terms alphabetically and tells the user what they are Designing Indexes and Gloossaries, Chapter 15 2

Why Use an Index? þ The index is a critical element of the software documentation. þ The index performs a unique function. 1 It directs the user straight to the material in the manual. Designing Indexes and Gloossaries, Chapter 15 3

Why Use an Index? (Continued) 1 The index meets the place of multiple users. 1 You may have both new and expert users, and the index serves as the meeting place of the vocabulary used by all users. 1 If correctly designed, the index will provide all users with the information they need. Designing Indexes and Gloossaries, Chapter 15 4

Guidelines for Designing Indexes 1 Decide on the indexing methodology 1 Decide what to index 1 Identify the level of detail 1 Decide on phrasing and format 1 Build and proofread Designing Indexes and Gloossaries, Chapter 15 5

How Will You Index Your Manual? 4 Many writers choose to create their indexes manually. 4 Pros: You know the material and concept Know what the user needs Designing Indexes and Gloossaries, Chapter 15 6

Creating Your Index Manually 1 Budget your time for indexing if creating a manual index. 1 List every term you think should be included, but don’t worry about page numbers. 1 Build a first draft of terms to be indexed into your beta or final draft. Designing Indexes and Gloossaries, Chapter 15 7

Manual Indexing 1 Begin to index when you have a copy of text with accurate page breaks so you can identify the page on which a reference appears. 1 The length of the index depends on the complexity of the manual. The more complex, the more pages. Designing Indexes and Gloossaries, Chapter 15 8

How Much Time to Index Manually? 1 Allow enough time for a thorough job. 1 Plan about three days or 25 hours for a 100 -page manual. 1 Plan about six days for a 250 -page manual (50 hours). Designing Indexes and Gloossaries, Chapter 15 9

Why Use an Index? þ The index is a critical element of the software documentation. þ The index performs a unique function. 1 It directs the user straight to the material in the manual. Designing Indexes and Gloossaries, Chapter 15 10

Why Use an Index? (Continued) 1 The index meets the place of multiple users. 1 You may have both new and expert users, and the index serves as the meeting place of the vocabulary used by all users. 1 If correctly designed, the index will provide all users with the information they need. Designing Indexes and Gloossaries, Chapter 15 11

Guidelines for Designing Indexes 1 Decide on the indexing methodology 1 Decide what to index 1 Identify the level of detail 1 Decide on phrasing and format 1 Build and proofread Designing Indexes and Gloossaries, Chapter 15 12

Electronic Indexes 1 Many word processing programs usually contain functions for indexing. 1 Advantages: Provides automatic alphabetizing Provides automatic formatting. (You don’t have to bother with indenting by hand. ) Ease of revision. l (You can change the index at the last minute. ) Designing Indexes and Gloossaries, Chapter 15 13

Using Automated Software 1 Disadvantages of Using Automated Software: Few synonyms appear Has to be looked up by the exact word. The organization tends to be flat not hierarchical and meaningful. An automated software package does not know the user. Designing Indexes and Gloossaries, Chapter 15 14

What Should Be Included? 4 Make References Count - - Don’t index every time a word is used. Make a general reference to a general topic discussion. 4 Include the main subjects, topics, and concepts: List all topics included in the table of contents. Invert phrases, such as disk drives, include drives, disk If an acronym is used, list the long form in the index, as well. Designing Indexes and Gloossaries, Chapter 15 15

What Should Be Included? (Continued) 1 Include all tasks your audience recognizes. Readers should be able to look up any type of task, large or small. Include every reason for using a particular command or sequence of commands. If items are listed by task, the user can look up information without having to know what command to use. Include all names by which the audience may refer to tasks, even if those names aren’t used in the product or documentation Designing Indexes and Gloossaries, Chapter 15 16

What Should Be Included? (Continued) 1 Include all commands, options, and arguments. 1 Include concepts (Users have to understand these basic concepts in order to understand how the program works. ) 1 Include all cautions. 1 Include references to key graphics. Designing Indexes and Gloossaries, Chapter 15 17

What Should Be Included? (Continued) 1 Include user terms to prevent potential questions 1 Tasks and procedures are critical. 1 Glossary terms (you include a reference in the index for all the terms in the glossary. ) Designing Indexes and Gloossaries, Chapter 15 18

What Should Be Included? (Continued) 1 Use proper names of products and companies, where appropriate. 1 A manual that supports information-oriented work should do its best to acknowledge connections to the larger business environment surrounding the user’s workplace. Designing Indexes and Gloossaries, Chapter 15 19

Identify Level of Detail 1 First-level indexes is frequently found in shorter manuals. 1 A first-level index may be completed by putting the table of contents in alphabetical order. 1 Two-level indexes organizes terms by categories. 1 These represent a more sophisticated organization of the material. Designing Indexes and Gloossaries, Chapter 15 20

Identify Level of Detail (Continued) 1 Third or higher level indexes 1 The most extensive index goes to three or more levels. 1 The amount of detail is also denoted by the number of indexable items per page. 1 A third or higher level index has an average of eight to nine items per page indexed. Designing Indexes and Gloossaries, Chapter 15 21

Compiling and Organizing Your List 1 You must go through every page manually. 1 You may have to make two to three runs to complete. The first may be a paper copy marked with a highlighter. The second pass may allow you to compile all your entries into a list. Designing Indexes and Gloossaries, Chapter 15 22

Don’t Leave Your Readers Asking What’s Up? Follow These Rules 4 Make your index hierarchical Using subentries makes it easier to group information and easier to find information. For example: printing • whole document • current page • from disk Designing Indexes and Gloossaries, Chapter 15 23

Rules for Indexing 1 Some terms can stand on their own in an index. 1 Start each subentry on a line of its own, indented under the main entry. 1 Lines that wrap to the next line should be indented to keep entries and subentries clearly organized. Designing Indexes and Gloossaries, Chapter 15 24

Rules for Indexing (Continued) 1 A subentry may also deserve a separate listing so a reader can find it alphabetically. 1 Cue the primary locator number in some way such as bolding. For example: Quick Start: 4, 8, 10 This indicates that the bulk of the information for the Quick Start may be found on page 10. Designing Indexes and Gloossaries, Chapter 15 25

Rules for Indexing (Continued) 1 You may want your entries to sound like sentences. For example: – Insert • New slide • Pictures • Hyperlink or – Insert • New slide • Pictures downloaded from the Internet • Materials to be used as hyperlinks Designing Indexes and Gloossaries, Chapter 15 26

Rules for Indexing (Continued) 1 Cue Special Terms 1 You may wish to bold or capitalize certain tasks commands or functions. 1 Capitalize terms consistently, i. e. -- all or none. Designing Indexes and Gloossaries, Chapter 15 27

Rules for Indexing 1 Pick a main entry for a topic. Try to make the entry most readers would look for first. Use logical alternatives. Just add, see monitors, videos Use see and see also immediately after the index heading, in parentheses, and italicize both words. Designing Indexes and Gloossaries, Chapter 15 28

Rules for Indexing 1 Subdivide topics When you accumulate more than a handful of page numbers for an entry, start making subtopics. Use the information in your notes and go back through the manual to pick out the best divisions. Designing Indexes and Gloossaries, Chapter 15 29

Sort Your Entries 4 An index is alphabetized. 4 It can either be alphabetized letter for letter or word for word. 4 The preferred method is letter by letter. 4 Ignore spaces, accent marks, and any capitals and look for the next letter up to the first punctuation mark. 4 If you alphabetize word for word, arrange entries by the first word, then the second, and so on. Designing Indexes and Gloossaries, Chapter 15 30

Make Your Index a Lighthouse to Those Who are Lost 4 When alphabetizing, put entries beginning with symbols at the beginning of the index, before entries that begin with letters. 4 List numbers alphabetically, as though they were spelled out. 4 Ignore words such as the, a, of when alphabetizing the first significant word. Designing Indexes and Gloossaries, Chapter 15 31

Edit the Listing 1 You’ll be the top banana, if you will. . . Compile, sort, review and edit your index. Designing Indexes and Gloossaries, Chapter 15 32

Also, Remember When Editing 1 Even if you find a great deal of redundancy, don’t cut meaningful alternate terms. 1 Review each term and make sure it would make sense to the reader. If you do that, you’re sure to make a hit. Designing Indexes and Gloossaries, Chapter 15 33

Use Consistent Style 1 Decide whether your index entries will be singular or plural. Be consistent throughout the index. It is generally accepted that you make entries in the index singular. 1 Watch your case and punctuation. 1 Use page numbers rather than chapter or section numbers. Designing Indexes and Gloossaries, Chapter 15 34

A Glossary Can Be a Mini-Dictionary 1 When you mention a new term for the first time, help the reader by defining it in the text. 1 Put new terms in a glossary. 1 A glossary defines words that may be unfamiliar phrases. 1 The more inexperienced your readers, the larger your glossary should be. Designing Indexes and Gloossaries, Chapter 15 35

Your Glossary Should Include 1 Key terms that are unfamiliar to users. 1 All technical terms 1 Acronyms and abbreviations in their short and spelled-out versions. 1 Words used atypically in the product. 1 Any idea that may present problems to users or puzzles you. Designing Indexes and Gloossaries, Chapter 15 36

Glossary Style 1 The first time you use a glossary term in the text, give it a distinctive format, such as boldface or italics. 1 Your definition of the term in the main text may be quite general. 1 The glossary entry should provide more detailed information. Designing Indexes and Gloossaries, Chapter 15 37

Define Without Repeating the Term 1 When writing a glossary definition, the first phrase should just define the term. 1 Don’t repeat the term. 1 A pepper is a pepper!!! Designing Indexes and Gloossaries, Chapter 15 38