Designing Indexes and Glossaries ITSW 1410 Presentation Media Software Instructor: Glenda H. Easter.

Designing Indexes and Designing Indexes and GlossariesGlossaries

ITSW 1410

Presentation Media Software

Instructor: Glenda H. Easter

Designing Indexes and Gloossaries, Chapter 15

2

Differences in an Index Differences in an Index and a Glossaryand a GlossaryAn 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


3

Why Use an Index?Why Use an Index?

The index is a critical element of the software documentation.

The index performs a unique function. It directs the user straight to the material in the

manual.


4

Why Use an Index? Why Use an Index? (Continued)(Continued) The index meets the place of multiple users.

You may have both new and expert users, and the index serves as the meeting place of the vocabulary used by all users.

If correctly designed, the index will provide all users with the information they need.


5

Guidelines for Designing Guidelines for Designing IndexesIndexes Decide on the indexing methodology Decide what to index Identify the level of detail Decide on phrasing and format Build and proofread


6

How Will You Index Your How Will You Index Your Manual?Manual? Many writers choose

to create their indexes manually.

Pros: You know the material and concept Know what the user needs


7

Creating Your Index ManuallyCreating Your Index Manually

Budget your time for indexing if creating a manual index.

List every term you think should be included, but don’t worry about page numbers.

Build a first draft of terms to be indexed into your beta or final draft.


8

Manual IndexingManual Indexing

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.

The length of the index depends on the complexity of the manual. The more complex, the more pages.


9

How Much Time to Index How Much Time to Index Manually?Manually? Allow enough time for a thorough job. Plan about three days or 25 hours for a 100-

page manual. Plan about six days for a 250-page manual

(50 hours).


10

Why Use an Index?Why Use an Index?

The index is a critical element of the software documentation.

The index performs a unique function. It directs the user straight to the material in the

manual.


11

Why Use an Index? Why Use an Index? (Continued)(Continued) The index meets the place of multiple users.

You may have both new and expert users, and the index serves as the meeting place of the vocabulary used by all users.

If correctly designed, the index will provide all users with the information they need.


12

Guidelines for Designing Guidelines for Designing IndexesIndexes Decide on the indexing methodology Decide what to index Identify the level of detail Decide on phrasing and format Build and proofread


13

Electronic IndexesElectronic Indexes

Many word processing programs usually contain functions for indexing.

Advantages:Provides automatic alphabetizingProvides 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.)


14

Using Automated SoftwareUsing Automated Software

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.


15

What Should Be Included?What Should Be Included? Make References Count - -

Don’t index every time a word is used. Make a general reference to a general topic discussion.

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.


16

What Should Be Included?What Should Be Included?((Continued)Continued) 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


17

What Should Be Included?What Should Be Included?(Continued)(Continued) Include all commands, options, and

arguments. Include concepts (Users have to understand

these basic concepts in order to understand how the program works.)

Include all cautions. Include references to key graphics.


18

What Should Be Included?What Should Be Included?(Continued)(Continued) Include user terms to prevent potential

questions Tasks and procedures are critical. Glossary terms (you include a reference in

the index for all the terms in the glossary.)


19

What Should Be Included?What Should Be Included?(Continued)(Continued) Use proper names of products and

companies, where appropriate. A manual that supports information-oriented

work should do its best to acknowledge connections to the larger business environment surrounding the user’s workplace.


20

Identify Level of DetailIdentify Level of Detail

First-level indexes is frequently found in shorter manuals. A first-level index may be completed by putting

the table of contents in alphabetical order. Two-level indexes organizes terms by

categories. These represent a more sophisticated

organization of the material.


21

Identify Level of Detail Identify Level of Detail (Continued)(Continued) Third or higher level indexes

The most extensive index goes to three or more levels.

The amount of detail is also denoted by the number of indexable items per page.

A third or higher level index has an average of eight to nine items per page indexed.


22

Compiling and Organizing Compiling and Organizing Your ListYour List You must go through every page manually. 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.


23

Don’t Leave Your Readers Asking Don’t Leave Your Readers Asking What’s Up? Follow These RulesWhat’s Up? Follow These Rules 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


24

Rules for IndexingRules for Indexing

Some terms can stand on their own in an index.

Start each subentry on a line of its own, indented under the main entry.

Lines that wrap to the next line should be indented to keep entries and subentries clearly organized.


25

Rules for Indexing Rules for Indexing (Continued)(Continued)

A subentry may also deserve a separate listing so a reader can find it alphabetically.

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.


26

Rules for Indexing Rules for Indexing (Continued)(Continued) 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


27

Rules for Indexing Rules for Indexing (Continued)(Continued)

Cue Special Terms You may wish to bold or capitalize certain tasks

commands or functions.

Capitalize terms consistently, i.e. -- all or none.


28


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.


29


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.


30

Sort Your EntriesSort Your Entries

An index is alphabetized. It can either be alphabetized letter for letter or

word for word. The preferred method is letter by letter. Ignore spaces, accent marks, and any capitals and

look for the next letter up to the first punctuation mark.

If you alphabetize word for word, arrange entries by the first word, then the second, and so on.


31

Make Your Index a LighthouseMake Your Index a Lighthouseto Those Who are Lostto Those Who are Lost When alphabetizing, put entries beginning with

symbols at the beginning of the index, before entries that begin with letters.

List numbers alphabetically, as though they were spelled out.

Ignore words such as the, a, of when alphabetizing the first significant word.


32

Edit the ListingEdit the Listing

You’ll be the top banana, if you will . . . Compile, sort, review and edit your index.


33

Also, Remember When EditingAlso, Remember When Editing

Even if you find a great deal of redundancy, don’t cut meaningful alternate terms.

Review each term and make sure it would make sense to the reader. If you do that, you’re sure to make a hit.


34

Use Consistent StyleUse Consistent Style

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.

Watch your case and punctuation. Use page numbers rather than chapter or

section numbers.


35

A Glossary Can Be aA Glossary Can Be aMini-DictionaryMini-Dictionary When you mention a new term for the first

time, help the reader by defining it in the text.

Put new terms in a glossary. A glossary defines words that may be

unfamiliar phrases. The more inexperienced your readers, the

larger your glossary should be.


36

Your Glossary Should IncludeYour Glossary Should Include

Key terms that are unfamiliar to users. All technical terms Acronyms and abbreviations in their short

and spelled-out versions. Words used atypically in the product. Any idea that may present problems to

users or puzzles you.


37

Glossary StyleGlossary Style

The first time you use a glossary term in the text, give it a distinctive format, such as boldface or italics.

Your definition of the term in the main text may be quite general.

The glossary entry should provide more detailed information.


38

Define Without Repeating the Define Without Repeating the TermTerm When writing a glossary definition, the first

phrase should just define the term. Don’t repeat the term. A pepper is a pepper is a pepper!!!

Designing Indexes and Glossaries ITSW 1410 Presentation Media Software Instructor: Glenda H. Easter.

Documents

Transcript of Designing Indexes and Glossaries ITSW 1410 Presentation Media Software Instructor: Glenda H. Easter.