Barker – Chapter 14: Designing Indexes

The index is one of the most valuable—and most popular—features of software documentation because it can lead users to exactly the right information. This chapter covers index methodology: how to decide what to index, levels of detail, phrasing, building, and proofreading.

Plan Your Indexing Strategy
There are two methods for creating an index: manual, in which you make notes as you read through a document, or electronic, in which a software indexing feature identifies terms.

Manual Indexes
To create a manual index, the document must be essentially complete so that page numbers are correct. The steps are as follows:
¨ Review the user analysis to remind yourself of how the software will be used
¨ Read or scan the page for index entries (main topics, concepts, and tasks; tables, figures, captions, examples, definitions, acronyms, and abbreviations; or menu names, tool buttons, and keyboard shortcuts)
¨ Record all index entry locations in a word processing file
¨ Alphabetize, edit, and format the index for consistency and usefulness

Electronic Indexes
An embedded indexing function is part of most word processing software programs.
These allow you to highlight terms and assign them to categories. It’s possible to index as you create the document, and then compile the index when it’s finished. Advantages to this method include automatic alphabetizing, automatic formatting, and easy revisions. The process is similar in some ways to manual indexing:
¨ Review the user analysis, keeping this in mind as you create the document
¨ Mark index entries as you write or edit
¨ Build the index: select the location and use the software to create the index
¨ Edit the index to eliminate inconsistencies, double entries, missing entries, etc. (Note: corrections must be made in the text, not the index.) Format, if necessary.

Decide What to Index
Try to make your index “support the activities and actions the user will undertake in applying the program to workplace needs.” Have developers, users, and other writers review the index specifications. Consider commands and functions (menu terms), concepts related to subject matter, user synonyms for program terms and proper names, user questions, glossary terms, and tasks and procedures.

Identify the Level of Detail
A very simple one-level index organizes the table of contents alphabetically. A standard two-level index includes main headings (categories), subheadings, and locator numbers. Three or more levels are very complex. An index may also be described by the number of “indexable” items per page of the document: a light index has 2-3 items, a medium one has 5-7, and a heavy index has 8-9 items per page.

Decide on Phrasing and Format
Writers need to plan the phrasing and formatting of index entries. Cue the primary locator numbers by bolding, capitalize terms consistently, make entries sound like sentences, and cue special terms.

Edit and Proofread
Carefully edit and proofread the completed index for mistakes such as indentation errors or inaccurate page numbers. Ask a user to review and test the index, if possible. Consider what content to emphasize and how to group information.

Discussion
Because indexing is often left until the end of a project, indexers may feel pressured to finish quickly because of publication deadlines. However, an index accesses the document from the user’s point of view and directs the user to the information they need. It is useful to beginners and advanced users alike.

A print index, located at the back of a manual, contains terms printed alphabetically in a two- or three-column format. An online index lists terms alphabetically and allows users to either scroll through the list or click on a letter from an alphabet display. A keyword search allows users to select a word from a list or enter one manually; a search engine then matches it to related topics. The writer is responsible for creating the electronic links. This type of search is often more limited than other types of indexes.

Microsoft Word, Adobe Framemaker, and other software programs have indexing capabilities. Some programs also work with HTML files. Problems occur when search engines retrieve too much irrelevant information to be useful, because they examine the entire text or web page. “Meta” tags can be used to locate certain responses identified by the web designer. However, information retrieval is complicated by partial words or misspellings.

Indexers rely on reference resources such as dictionaries, thesauri, encyclopedias, fact books, phone directories, organizational listings, geographical maps, and other collections of information (for example, science, medicine, business, law, agriculture, or computer terminology). As Barker notes, “These kinds of resources can help the indexer make the crucial matches between the vocabularies of a software program (represented by the words that make up the interface) and the terminology used by and familiar to the user.”

Beyond Skill Building: Challenges Facing Technical Communication Teachers in the Computer Age

(By Stuart A. Selber, Originally printed in 1994)

Teachers of technical communication often focus on teaching their students computer technologies to help prepare students for future employment responsibilities. However, this focus on technical skills may be at the expense of “critical political and ethical understanding.” Critical and rhetorical skills and other humanistic issues should not be neglected.

Selber researched course descriptions from 39 colleges and universities offering technical communication programs to determine why and how computers were used in the classroom. His purpose was to identify areas of instruction that were “under-represented as well as identify concerns important to productive teaching about and with computers.”

As might be expected, there was a large variance in what was considered appropriate to include in the programs. While most basic tech comm classes had expectations that students would use word processing programs and print on laser printers, others were teaching “hypertext and hypermedia, (asking) students to work collaboratively online, (or requiring) them to join electronic conversations in their specialty areas for interaction with professional writers and editors in business and industry.”

Selber categorized the instructional goals of the technical communication courses and found that most courses focused on one of three objectives: “production; computer literacy; and situating technology in historical, political, and social contexts.”

Production Courses

Many of the courses focused on skill building and learning computer processes that would be of value in the workplace. They were further categorized as follows:

· Computer Applications Courses: hardware and software skills

· Document and Graphic Design Courses: skill-building in desktop publishing and graphic design programs

· Publications Management Courses: the nuts and bolts of producing technical publications, such as editing, layout and visual design principles, as well as scheduling and budgeting

· Specialized Writing Courses: focusing on a specific genre in technical communication such as proposal or report writing

· Introductory Writing Courses: introductory technical writing

Computer Literacy Classes

These courses attempted to teach about computer technologies as related to broader theories such as reading, writing, or even psychology. For example, a class dealing with visual design might incorporate topics such as the “human visual system” or “theories of perception and attention.”

Courses Situating Technology in Historical, Political, and Social Contexts

The purpose of this type of instruction was to transcend the “skill-based approach” in order to help students understand how technology shapes societal, historical, or political issues and how “implementing and using computer technologies are fundamentally ideological acts.”

Selber felt that teachers might be “reluctant to engage in a critical examination of our culture’s technological foundation.” Many explanations were given as to why computers were being incorporated into the curricula. Besides the common rationale that teaching technological skills would increase students’ marketability, other reasons given included the necessity of building required skills necessary for technical communication activities, improving students’ writing, and promoting collaboration.

By examining how computers were being used in the classroom, Selber hoped teachers would prepare students who were “literate and responsible users of computer technology.” He discussed three main challenges that teachers might consider when answering the question, “Why are computers used in our curricula?”

Challenge #1: Balancing Technological with Literacy and Humanistic Concerns

Although the most common reason cited for teaching technology was to help to prepare students for their future employment, Selber felt that if this was the main focus, teachers would lose sight of the literacy and humanistic issues that are also important. When planning programs and course offerings, he stressed the importance of balancing the different types of classes that are outlined above.

Challenge #2: Re-Envisioning our Computer-Related Curricula

He also felt that current programs and classes needed to be examined to determine if enough emphasis was being given to humanistic and literacy issues in teaching technology. Selber said that “too often we integrate computers in our classrooms without a critical rethinking of how they might inhibit our instructional goals.”

Challenge #3: Educating Teachers who Use Computers in Their Classrooms

He also encouraged faculty, staff, and graduate assistants to learn how to incorporate computers into the classroom. Selber found very little guidance for doing so, and he called this “shortsighted.” Because of the rapid changes in technology, he cautioned instructors to not only keep pace with the change, but to function as “technology critics and reformers” and to understand how to responsibly teach technology to their students.

Barker Chapter 12: Getting the Language Right

An important method in writing software manuals is to do so in a way that is performance-oriented.

Guidelines

There are five guidelines Barker writes about regarding user-oriented style:

1. Write about actions rather than functions.
   Structure the language to support the resulting actions of functions. Identify the function and then explain what the user can do with it. The more you focus on usefulness rather than on functions, the more the user will realize that usefulness.


2. Revise for the active voice.
   Revise statements to include active voice. See Table 12.1 on page 386 for examples.


3. Revise to keep writing simple
   Simplicity helps every aspect of manual writing. Avoid extra filler and similar unnecessary information. Keep the subject and verb together.


4. Revise to build parallel structures
   Consider parallelism (for example, consistently using the same grammatical structure such as verb ending ing in headings) as consistency keeps a document's content from becoming confusing. Check Table 12.2 on page 388 for examples.


5. Add operational overviews
   Providing overviews cuts down on confusion for users who may not be completely familiar with the material. Tell them how the program benefits them. "Your 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" (389). Writers primarily use three ways to emphasize explanations of abstract concepts: "the theoretical (emphasizing the theories behind the working of the program), the technical (emphasizing the technical functioning of the program), and the operational (empasizing the application of the program)" (389). Check Table 12.3 on page 390 for more details.

Discussion

"In software documentation, you will often use different writing styles and different tones to support different user tasks" (390). So,

How Do We Process Language?

First, you need to write words in a way that connects with the user. Information needs to be significant to them.

Users have specific searching behavior or problem-solving strategies, so the document information should appropriate the energy the user puts into specific tasks. The amount of meaning a text has depends on the user's task.

Performance-Oriented Language

Slow read-through rarely pays off. To avoid this problem, the software manual writer should use

• active voice.
• the pronoun you to make the text interactive.
• imperative verbs to trigger actions.
• real language (language that the reader can actually understand and learn from rather than formal language).

How Do We Remember and Learn

Users need to remember ideas they read in order to learn. Try to make connections with the user's memory; this will trigger those memories and will make learning easier.

Structured Sentences

Thorough knowledge of how to structure information clearly in sentences is essential for retention. Sentences should be simple and short.

Style Problems in Software Documentation

Styles issues such as too many abstractions, little performance support, and overly complex syntax will make your information difficult to use (See Table 12.4 on page 393 for more details).

Acronyms

Acronyms can make complex systems easier to define; however, overusing them is not recommended. They will show up, though as software systems often contain hundreds of them. They also can save a lot of time.

Synonyms

Synonyms should be used consistently but carefully as they may be similar, but can evoke different meanings. One option to consider regarding this is indexing.

Paragraphs and Sentences Too Long

Paragraphs should focus on explanations, not performance, and not on steps telling the reader what to do. They work best when they support a simple concept. "They help explain what happens after a step, and, because the user will not usually tackle paragraphs unless he or she must, they shuld read as quickly and easily as possible" (395).

Emphasizing the Computer Instead of the Program

Since the user interacts with the program rather than the computer, you should create information that focuses on working with the software.

No Connection Between the Heading and the Topic

Headings must be meaningful, and the topic following should support that information. Specific explanations are usually all that's needed.

Too Formal Tone

Make software documentation conversational, not too formal. Sentences are meant to connect with another real person. Speaking in an informal tone makes contact more quickly and evokes the user's desire to do well on the job.

When to Use Humor

Avoid it. That's the impression I got from the reading.

Ambiguous Task Names

Avoid making vague references. "In task-oriented documentation you should name tasks clearly, with a sense of planning for the user's new vocabulary" (398). The name of the task should appear frequently in the text of the manual.

Step Not a Step

Examine youre steps to make sure they contain a clearly stated action, often using an imperative verb.

Thanks! Team 3 (Carlson and Hood)

Barker, Chapter 13: Using Graphics Effectively

Graphics are an important part of technical documentation.

1. Identify Needs for Graphics by Your Users
Graphics in technical documentation assist the user in using the program and working with it.

Use graphics to support the questions you believe your users may have:

Where is it?
Graphics can support users in locating menus and buttons they will be using. Screen shots are great images to assist in locating these menus and buttons, so the user can see exactly what it is being discussed in the writing. It is very important that graphics are clear and understandable to the user.

What is it?
Use graphics to help users understand concepts. This includes examples and metaphors. Examples include printouts, reports, and documents and should be clearly explained. Metaphors explain something to the user in a way that they already understand. Most metaphors are language-based, but images increase the understanding of the metaphor. For example, users understand that the word and image of a mailbox stands for email.

How do I do it?
Users appreciate step-by-step instructions when learning something for the first time, and graphics really help in their understanding. Flowcharts are effective graphics to achieve this.

Where am I?
Access indicators and progress indicators are appropriate graphics to show users where they are at in a manual or help system.

What's the big picture?
Some graphics you can use to show overviews of programs include overall program diagrams, menu maps, conceptual overviews, and a page showing how to use the manual.

2. Set Graphics Styles
Your graphic styles should be consistent throughout the entire document. In some cases, it may be best to reduce the complexity in some graphics to allow the user to focus on what is most important in the image. Having a thorough knowledge of your graphics preparation tools will help you when it comes time to select which styles you will use.

3. Revise and Edit
When revising graphics, consider these guidelines:

- Give your graphics a clear purpose;
- Titles: complex images often require titles for clarity;
- Callouts: use callouts judiciously; they are most effective when not overused;
- Placement: place graphics consistently and as near to the text that refers to them as possible;
- Rules: rules and lines should be used sparingly to help give the page structure;
- Size: not too big, not too little; crop to show pertinent details; surround with white space;
- Colors: colors should reflect the patterns of information in the text.

4. Revise for Typography
Arrange images according to the logical structure of the information they contain. Make important things larger, darker, more central, and sharper. Align related things--first things to the left, later things to the right.

Discussion
Describe operations in a way that helps the user do meaningful work. You can do this by:

- Showing how tools apply to the workplace;
- Showing the results of software operations: most commonly these show the screen that appears after the keyboard/mouse has been used;
- Presenting overviews to integrate software with workplace activities: this helps user understand how the manual has been designed to work;
- Suggesting functions and uses: this can give the users ideas about how the software can benefit them;
- Using metaphors to make the abstract concrete; people love metaphors because they help them relate something new to something they already understand.

Chapter 12, Campbell, “We’re Thinking about Going On-Line”

What is means to Go On-Line There are advantages and disadvantages of going on-line with policies and procedures; going on-line should be a deliberative decision. It is not a magic solution; rather, it is a different method to delivering your final product to your users.

What Means to Go On-Line: What Does Not Change

• the content of policies and procedures
• development process
• writing, review, editing, or content revision process
• challenges of decision making,
• and careful planning and writing

What Means to Go On-Line: What Does Change

• Method of communication of final product-there is no physical product
• Different delivery system

Advantages and Disadvantages of Going Online

Advantages (also see the table on pg 374)

• faster and more efficient than a paper system
• messages delivered instantly and simultaneously to many users
• online system may be less costly to maintain
• saves storage space
• fewer deadlines pressures for writer (do not have to wait on the printing process)
• users can find related documents and information faster through searches or hypertext
• users may be less intimidated to turn to the machine

Disadvantages (also see the table on pg 375)

• users who aren’t comfortable with computers may be intimidated
• requires major commitment from organization to supply time, training, and even empathy for users
• may require significant budget (software, hardware, etc)
• readability is less in comparison to paper document
  -may have visual problems
  -may be hard for users to distinguish between a “page” and a “screen”
• may not always be available (such as if the system crashes)

The Case of External Users
On-line systems for external users (like customers) also present special challenges. Such as, potential users will need to know how to operate a computer and feel comfortable with it. The problem lies is wherein that you cannot train all external users. You will need to investigate and analyze external factors. Analyze whether external users will have the software needed, and if their surroundings are conducive to use (lighting, physical proximity, etc).

Designing an On-Line System
The limited readability and computer screen create certain design conditions. The format and design of your documents will be much different on-line from on paper. These are the four design factors to keep in mind:
1. visual simplicity
2. ease of use
3. clear operating instructions
4. adequate conversion of elements such as acknowledgement and revisions

See the On-Line Tip Sheet for a full explanation of these factors (12-1).

Thanks! Team 2: Jennifer & Gary

Central Works Essay 31

Cross-Cultural Collaboration: Whose Culture Is It, Anyway?

Deborah S. Bosley wrote this essay in 1993. She had previously written many articles about collaborative work and considered herself very knowledgeable about all aspects of the subject. Then two of her international students taught her something new when they discussed some cross-cultural issues on their evaluation forms after working on a collaborative project. Cross-cultural collaboration is something she had never even thought about. At the time, there wasn't much research done on it. This article was written after this introduction to cross-cultural issues in collaboration. She believes it is still valid today.

Definitions and Caveats

The common belief is that everyone learns the same, no matter what their race or backgrounds. Research in multicultural communication shows that differences do exist.

Without taking into account the context of a person's culture, it is impossible to understand the problems they might face in a collaborative group.

Cultural Differences in Behavior

Euro-North American culture places emphasis on individuality. Competitiveness is taught to children rather than collaboration, like in many other cultures. The success and achievements of Euro-North Americans are measured individually, even in group settings. The idea is that this competitiveness increases the productivity of the group. Other cultures believe this causes problems and could decrease productivity. Euro-North Americans praise those who make their own decisions, while those in communalistic cultures, such as many Asian cultures, believe that it is disrespectful to put your decisions above those of the group.

There are differences in oral and written communication for members of different cultures. Examples of oral differences lie in the use of context, comfortableness with silence, and exaggeration. Written differences include the organization and structure of texts.

Strategies for Internationalizing Collaborative Groups

Groups should recognize and take into consideration any cross-cultural differences that lie within their group right from the beginning. Group members can learn from one another and learn to appreciate each member's strengths and differences. Every member can gain positive effects from cross-cultural communication.

The Shape of Text to Come: The Texture of Print on Screens

In 1993, when author Stephen A. Berhnardt wrote this article, the World Wide Web was in its infancy and computer use was just starting to become common in the workplace. The author describes it as a “speculative piece” that tried to describe the transition from paper text to on-screen text.

Bernhardt considers what constitutes a well-formed text, how readers interact with text, and how text differs in print and on screen. He notes that paper documents have provided a starting point for both rhetoric and structure of on-screen text. In this paper, Bernhardt examines a number of features that are unique to electronic text.

Situationally Embedded Text

Books and other paper texts have different attributes than on-screen text. These documents are portable. Their use is typically independent of the reader’s physical environment; in fact, they allow the reader to escape by portraying a completely different situation.

Screen-based text, on the other hand, is integrated with other actions. It is typically task-based: readers use the text for researching, writing, editing, tracking information, sharing and collaboration. “Reading,” Bernhardt says, “is not the primary goal.”

Interactive Text

On-screen text allows readers to physically interact with the text, manipulating and transforming it through the use of a mouse, and controlling the outcomes. Research shows that this type of participatory learning leads to better retention of text material. Unlike writers of print materials, “writers of on-screen text can force interaction, making it necessary for the reader to do something in order to get to the next step.”

Functionally Mapped Text

Text of any kind functions to inform, direct, question or pose situations for readers. The rhetorical purpose is apparent through the use of signals such as visual cues (layout, typography) and syntactic cues (grammatical structure, certain phrases). In addition to these signals, electronic text can incorporate buttons, icons, hyperlinks and menus that provide specific functions. Writers of on-screen text, in addition to creating content, must map these cues to their actions.

Layout conventions help readers locate information. For example, the periphery of the screen contains the most action. Bernhardt says, “It is on the edge that we recognize where we are, what we can do, where we can go, or how we can get out.”

Modular Text

Texts are composed of other texts: books have chapters; magazines have articles, sidebars, and tables of contents; and encyclopedias have individual modules. Because of the limitations of computer screen dimensions, electronic text requires screen-sized chunks of highly localized text. There are problems with cohesion due to screen boundaries; “the break from one screen to next presents a larger gap than that from one page to the next.” If scrolling is required, readers may choose to skip text below the screen view. Long sections of text cause readers to lose their place or become disoriented.

Readers pay more attention to idea groupings, or modules (no bigger than a computer screen). Information modules provide an advantage to writers as well, making it easy to rearrange information for different purposes or audiences.

Hierarchically Embedded Text

In addition to encapsulating information in easy-to-read chunks, modularity helps readers identify importance of text. Semantic cues tell reader that information is mainline, peripheral, supportive, or explanatory. Supporting information is present but not necessarily visible unless the reader follows links or help topics to additional information.

This hierarchy allows users to choose what to read. Unlike books, which must be read in a linear fashion, on-screen text allows readers to jump back and forth between multiple open files. The use of a cascading design displays high-level information but allows access to more detail for each topic

Navigable Text

All text must be navigated by readers. Paper text “signposts” include the table of contents, index, headings, headers, and page numbers. Features such as these give readers a sense of control. These navigation strategies do not work well for electronic text, however.

On-screen text does not allow readers to “size up” the whole document to assess how much information it contains, or how much they have already read. This is complicated by multiple layers of embedded text. Book-like options such as menus, indexes, pagination, and back/forward arrows can be combined with links, buttons, and icons, as well as graphical browsers with an explodable index. Electronic navigation cues and landmarks are becoming more standardized.

Spacious Text

Print text is limited by physical factors such as space, size and weight of the document. Writers must conform to these limitations when composing text. On-screen text, on the other hand, allows unlimited information and unconstrained design, and writers gain freedom from “economic constraints of inscription.”

Graphically Rich Text

Many graphical features are common to print and on-screen text: white space, space breaks, margins; bulleted or numbered lists; fonts, headings, boldface, and italics. Electronic text has more graphic potential, such as zooming, animation, video, sound, and three-dimensional views; and text-graphic display and integration.

Customizable, Publishable Text

On-screen text is easy to create and produce. Software editing/collaboration programs offer in-text markup with accept/reject features, “sound bites” for verbal commentary, and user profiles for customizable displays. Traditional document production costs have shifted from paper, printing, and binding, to authoring software and specialized hardware. The “fluidity” of on-screen text makes multiple versions and updates easier than ever

Conclusion

On-screen text is real-time and interactive, a fluid, changeable medium that allows users to control the final product more easily than with print text. Readers are developing new strategies for reading and writing, and have increasing comfort with on-screen navigation. The computer has become the dominant medium for presenting and working with texts.