Katy Mears
Erik Sorensen
Chapter 14 Barker: Designing Indexes
Two kinds of index methodology: manual or electronic
Chapter focuses on: what to index, levels of detail, phrasing, and techniques for building and proofreading.
1. Plan Your Indexing Strategy
A manual index requires you to go through the document and write index entries on cards or in a file. An electronic index uses the indexing feature of your software to make the index (437-438).
Manual Indexes: After finishing the document, write index entries down and alphabetize them. To determine index topics, follow these basic steps:
1. Review the user analysis to refresh yourself about the user’s needs.
2. Pick out terms/phrases that should be indexed. Look for: tables, figures, captions, main topics, important concepts, tool buttons, keyboard shortcuts, menu names, main tasks, examples and figures, definitions of terms, and acronyms or abbreviations.
3. Record the locations by page number
4. Alphabetize and edit the entries. Make sure all entries are consistent with formatting.
Electronic Indexes: Word processing software contains functions for indexing, often called “embedded indexing.” By identifying a term on the page and categorizing it, the program generates an index for you, as long as the entire document is in one file or a series of files. There are several advantages—automatic alphabetizing, automatic formatting, and ease of revision (ability to change entries at the last minute). The process is basically the same, with a few minor differences.
1. Review the user analysis to refresh yourself about the user’s needs.
2. Mark the index entries. Use the electronic marking feature of the software to determine the entries. You can do this as you are writing or editing.
3. Build the index. The software should automatically record and index entries and page numbers.
4. Edit the index. Check for inconsistencies such as double entries and missing entries. Edit the marked text not the index itself.
2. Decide What to Index
Many types of information can be indexed. Keep the user analysis in mind and you decide what types of information need to be indexed. The index should “support the activities and actions that the user will undertake in applying the program to workplace needs” (440). Make sure the documentation plan has specifications for indexing, if not, determine what they are and add them.
Index Categories:
Commands and Functions: Terms found on the menus. Format commands so they sound like parts of sentences.
Concepts: Ideas that are related to the subject matter. User must understand these to make the program work.
User Terms and Questions: Connect words the user knows to synonyms used in the program. For example, the software uses “quit” but the user may use “exit.”
Glossary Terms: Include a reference in the index for all the glossary terms.
Proper Names of Products and Companies: If your program writes files in formats usable by other programs or you refer to other companies you do business with, these should be included in the index.
Tasks and Procedures: A special index is sometimes needed for tasks and procedures. Tasks should be highlighted in a way that alerts the user to the guidance and step-by-step instructions.
3. Indentify the Level of Detail
Simple indexes have only one level and only show main headings. They are used for short documents. Two-level indexes organize terms by categories. Three or more levels make a complex index to organize many different types of information. See Table 14.1 for examples of the levels (444).
Light, medium, and heavy indexes show detail in another way. A light index has two to three items per page. A medium index has five to seven items per page. A heavy index has eight to nine items per page.
4. Decide on Phrasing and Format
You should spend some time planning for the phrasing and format of your index entries. There will be some issues such as being consistent in capitalization and bolding certain entries as opposed to others. Make sure to pay attention to special formatting of commands, tasks and functions.
5. Edit and Proofread
Once the index is created you should edit and proofread it for mistakes. Also make sure to pay attention to indents and page references to ensure their accuracy. Editing an index can take up to a 1/3 or the time devoted to creating an index. It’s important when editing to keep in mind the intended user’s characteristics.
Why an Index?
The index will express the overall organization of the document and puts the information in the user’s language. It provides direct access to the desired information. The index may even be put before the table of contents in some documents. The index also introduces the user to the vocabulary of the document.
Online Index vs. Print Index
Print Index – usually at the back of the book and divided by alphabet
Online Index – this type is often seen on websites. Allows scrolling of the index by selecting the letter.
Keyword Searches – Allows user to enter words in manually and then the search will determine the closest related topic. Usually focuses strictly on help topics.
Automatic Indexing Software Programs
There are a number of programs that exist that can create indexes automatically. The programs will do the majority of the examining and then organize information creating links to the topics. The user will still have control over the final product. Often the more exotic the indexing software, the more detailed an index can become.
Indexing with Search Engines
Often times indexing with search engines that examine the whole text provide results that have very little relevance to the desired outcome. To alleviate this problem, many search engines will filter out words that are determined to be useless. Because of the misspellings and other user errors many people have determined search engine indexing to create more work rather than lessen the work load.
Tools for Indexers
The American Society of Indexers (http://www.asindexing.org) lists a number of reference tools for indexers.
Other resources include:
· Dictionaries, thesauri and other language tools
· Encyclopedias, fact books
· Phone directories, geographical maps
Friday, April 11, 2008
Monday, April 7, 2008
Barker Chapter 13 Using Graphics Effectively
Graphics in manuals reinforce the key role images play in informing the user.
1.Identify needs for graphics by your users
Graphics should support user questions:
-How can I use the program easily? Use graphics to help user locate & act by providing images that educate, guide, and support workplace tasks.
-How can I put the program to work? Use graphics to help user understand by strategically placing them, helping to locate and direct
actions, explain concepts, and illustrate examples.
*Identify user questions then choose graphics to respond to user questions.
Where is it? Show user where to look to perform tasks: let the page reflect the screen; use capture and art programs to bring elements off the screen & into manuals & online help. Show concrete versions of abstract things: use images to emphasize important points & show how the program works. Make visuals clear: avoid clutter
What is it? Use graphics to define unfamiliar concepts to the user. Two types of graphics:
1) examples: show documents, reports, printouts, sample data. Explain & label graphics. Use examples liberally in high-tech, command-driven programs such as compilers, scientific graphing & analysis software & operating systems.
2) metaphors: show relation of ideas by relating to something familiar to user & allows users to rely on previous experience. Metaphors compare two things: the abstract & the concrete. Examples of metaphors: radio buttons, sliders, pull-down menus. Language metaphors are stronger if supported by the actual images suggested by the words.
How do I do it? Provide overviews of procedures introducing users to the steps that follow. Example of mental model: input-process-output.
Where am I? Access indicators show users their location in a manual or online help rather than tell them and keeps user from feeling lost. Examples of access indicators: diagrams showing current location in the process, history maps, header & footer icons. Progress indicators are helpful in tutorials so readers can easily see progress through the number of pages or lessons using headers or footers.
What’s the big picture? Users unfamiliar with computing or a new program need to know how it’s all put together (structured) since they cannot draw on previous experience. Experienced users may need reminders and expert users expect to have a structure in place. Keep things as small as possible when creating an overview graphic and use icons to make the connections between things seen on the screen and workplace demands. Color can be used for easy recognition. Some graphics elements to use:
Overall program diagrams: illustrate program system components to show the flow of information.
Menu maps: consist of program menus arranged on a page in the same structure they appear in the program interface; they help maintain as sense of organization of the program’s features.
Conceptual overviews: they reinforce the ideas of how to use a program; help users see how to employ the program in meaningful work through sharing information and resources. Guideline for designing conceptual overviews found on page 418.
How to use the manual: To determine what type of graphics to use to respond to user questions see Figure 13.13 on page 419.
2.Set graphics styles
Consistency is key! Use same types and fonts, same arrow styles, and box, and frame styles throughout your document. Table 13.3, page 421 lists elements of graphical styles. There may be advantages by deleting drawing details and using a cartoon or line drawing style since they help focus user attention on specific elements of a drawing. Photo realism in graphics uses more hard disc and CD storage space. Pre-planning is a good idea and the sooner you decide major issues such as size, type, graphic size, etc. the better.
3.Revise and edit
Once you’ve determined the kinds of graphics you’ll use, and have a working draft, you can revise for overall correctness and consistency. Watch for overcrowding, images, or text.
Guidelines for graphics revising:
Titles: Titles aren’t required on everything. Rule of thumb is the more complex, the more the need for a title. If user can’t easily see the relationship between the image and the text, add a title to clarify the image’s function. More guidelines page 423
Labels: Labels aren’t required for everything; they point out the salient elements of a picture or drawing and direct the user to the correct and informational parts. If you do label see page 423 for guidelines.
Placement: guidelines page 244
Size: guidelines page 244
Colors: guidelines page 245
4.Revise for typography
This means giving an arrangement to the images based on a logic. When using images, arrange and design to convey the meaning you intend. Guidelines: make important things larger, darker, central, and sharper, align related things, put first things left, later things right.
DISCUSSION:
Graphics make clear connections between software operations and workplace actions by:
• Showing how tools apply to the workplace
• Showing results of software operations
• Presenting overviews to integrate software with workplace activities
• Suggesting functions and uses: capture the typical-use scenario
• Making abstract concrete through the use of metaphors
1.Identify needs for graphics by your users
Graphics should support user questions:
-How can I use the program easily? Use graphics to help user locate & act by providing images that educate, guide, and support workplace tasks.
-How can I put the program to work? Use graphics to help user understand by strategically placing them, helping to locate and direct
actions, explain concepts, and illustrate examples.
*Identify user questions then choose graphics to respond to user questions.
Where is it? Show user where to look to perform tasks: let the page reflect the screen; use capture and art programs to bring elements off the screen & into manuals & online help. Show concrete versions of abstract things: use images to emphasize important points & show how the program works. Make visuals clear: avoid clutter
What is it? Use graphics to define unfamiliar concepts to the user. Two types of graphics:
1) examples: show documents, reports, printouts, sample data. Explain & label graphics. Use examples liberally in high-tech, command-driven programs such as compilers, scientific graphing & analysis software & operating systems.
2) metaphors: show relation of ideas by relating to something familiar to user & allows users to rely on previous experience. Metaphors compare two things: the abstract & the concrete. Examples of metaphors: radio buttons, sliders, pull-down menus. Language metaphors are stronger if supported by the actual images suggested by the words.
How do I do it? Provide overviews of procedures introducing users to the steps that follow. Example of mental model: input-process-output.
Where am I? Access indicators show users their location in a manual or online help rather than tell them and keeps user from feeling lost. Examples of access indicators: diagrams showing current location in the process, history maps, header & footer icons. Progress indicators are helpful in tutorials so readers can easily see progress through the number of pages or lessons using headers or footers.
What’s the big picture? Users unfamiliar with computing or a new program need to know how it’s all put together (structured) since they cannot draw on previous experience. Experienced users may need reminders and expert users expect to have a structure in place. Keep things as small as possible when creating an overview graphic and use icons to make the connections between things seen on the screen and workplace demands. Color can be used for easy recognition. Some graphics elements to use:
Overall program diagrams: illustrate program system components to show the flow of information.
Menu maps: consist of program menus arranged on a page in the same structure they appear in the program interface; they help maintain as sense of organization of the program’s features.
Conceptual overviews: they reinforce the ideas of how to use a program; help users see how to employ the program in meaningful work through sharing information and resources. Guideline for designing conceptual overviews found on page 418.
How to use the manual: To determine what type of graphics to use to respond to user questions see Figure 13.13 on page 419.
2.Set graphics styles
Consistency is key! Use same types and fonts, same arrow styles, and box, and frame styles throughout your document. Table 13.3, page 421 lists elements of graphical styles. There may be advantages by deleting drawing details and using a cartoon or line drawing style since they help focus user attention on specific elements of a drawing. Photo realism in graphics uses more hard disc and CD storage space. Pre-planning is a good idea and the sooner you decide major issues such as size, type, graphic size, etc. the better.
3.Revise and edit
Once you’ve determined the kinds of graphics you’ll use, and have a working draft, you can revise for overall correctness and consistency. Watch for overcrowding, images, or text.
Guidelines for graphics revising:
Titles: Titles aren’t required on everything. Rule of thumb is the more complex, the more the need for a title. If user can’t easily see the relationship between the image and the text, add a title to clarify the image’s function. More guidelines page 423
Labels: Labels aren’t required for everything; they point out the salient elements of a picture or drawing and direct the user to the correct and informational parts. If you do label see page 423 for guidelines.
Placement: guidelines page 244
Size: guidelines page 244
Colors: guidelines page 245
4.Revise for typography
This means giving an arrangement to the images based on a logic. When using images, arrange and design to convey the meaning you intend. Guidelines: make important things larger, darker, central, and sharper, align related things, put first things left, later things right.
DISCUSSION:
Graphics make clear connections between software operations and workplace actions by:
• Showing how tools apply to the workplace
• Showing results of software operations
• Presenting overviews to integrate software with workplace activities
• Suggesting functions and uses: capture the typical-use scenario
• Making abstract concrete through the use of metaphors
Sunday, April 6, 2008
Chapter 11 Barker: Getting the Language Right
This is just a comment on Barker's chapter 11, not the initial blog!
The concepts Barker writes about seem to follow the guidelines for all writing such as using active voice, keeping writing simple and geared to the user, and using the parallel structure. I thought he nailed it exactly with the idea that "A manual is like a bathroom key: people want to get their hands on it not because of its intrinsic properties but because it lets them do what they need to do." Perfect. I look for exactly this in any manual. I want the information I need and the rest can wait until later, or never.
I learned about explaining abstract concepts when writing and, at my job, I usually use the operational concept that simply tells me what I need to know. I think AuthorIt might fall into the technical functioning of a program and that may be where I'm experiencing difficulties because I'm required to understand the technical aspects in order to perform what I need to do for the documentation project. I'm more interested in the productivity of AuthorIt than learning the technical parts. And that might be where the sticky part lies.
Understanding the different types of parallelism helps with all tutorial and instruction writing. Parallelism seems to work well in tutorials because it's based on action by the user and that is what our documentation and usability projects require in the quest to be user friendly and user helpful.
The concepts Barker writes about seem to follow the guidelines for all writing such as using active voice, keeping writing simple and geared to the user, and using the parallel structure. I thought he nailed it exactly with the idea that "A manual is like a bathroom key: people want to get their hands on it not because of its intrinsic properties but because it lets them do what they need to do." Perfect. I look for exactly this in any manual. I want the information I need and the rest can wait until later, or never.
I learned about explaining abstract concepts when writing and, at my job, I usually use the operational concept that simply tells me what I need to know. I think AuthorIt might fall into the technical functioning of a program and that may be where I'm experiencing difficulties because I'm required to understand the technical aspects in order to perform what I need to do for the documentation project. I'm more interested in the productivity of AuthorIt than learning the technical parts. And that might be where the sticky part lies.
Understanding the different types of parallelism helps with all tutorial and instruction writing. Parallelism seems to work well in tutorials because it's based on action by the user and that is what our documentation and usability projects require in the quest to be user friendly and user helpful.
Subscribe to:
Posts (Atom)