Chapter 5 (Barker): Analyzing Your Users

The first step in the documentation process is to gather information about users. Barker outlines eight analysis areas and begins the chapter discussing the planning required prior to user analysis.

User Analysis Preparation and Planning

Before the user analysis inquiry begins, considerable time must be spent planning. Barker identifies the following guidelines for conducting a user analysis:

• Choose users carefully. Begin by thinking about as many groups of users as possible and create a list. To choose which users to analyze ask yourself which users would most likely use the program and which users would be the most realistic group for you to interview. Start to build a list of tasks/activities users will use the program for.
  
• Study users before and after using a program. Pay attention to the tasks/activities the users perform without your program. According to Barker, “Research shows that skills learned in the workplace can transfer to skills using software.” [122] Observe the work area for “artifacts” (notes, manuals, cheat sheets) that may provide clues about user habits. Observe what values confront the users (team skills, efficiency, ethical issues, etc.) to help understand their attitudes.
  
• Research professional behaviors. If you don’t have access to actual users, create a model by research a user’s occupation through reference materials and/or company documentation.
  
• Write use cases. Your goal is to find out what motivations, behaviors, values, and attitudes exist beyond what you can immediately observe. One approach to discovering this information is to write a use case. A use case is a narrative of a user’s “normal” work pattern. An example follows: Every Monday morning, Randy retrieves the updated sales figures for a weekly 9 a.m. meeting. He must first….” The author recognizes the above process takes time but does provide a visualization of the user.
  
• Plan interviews carefully. User interviews provide the most significant user analysis feedback. Take time to carefully plan for user interviews to avoid repeat visits or unproductive interviews by reviewing software and identifying issues, writing questions, and determining scope of interview.
  
• Involve users in all phases of the project. User analysis should take place throughout the entire documentation process: writing, reviewing, and testing. Involving the users through the process assists in establishing a working relationship with them, which allows you a better opportunity to “situate his or her actions in the workplace.” [133] A focus group can also be established and used throughout the documentation process.
  
• Identify document goals. Clearly identify what you expect to do for the user: “the activities you want to support and the user performance you want to empower.” [135]
  
• Tie the user analysis to document features. Make sure to tie the user analysis to the software documentation. Jot down ideas obtained throughout the user analysis process. Finally, match document features with the results of the user analysis process.

User Analysis

The purpose of user analysis is to study the user in the context of his/her work environment to see what tasks the user performs with the software while at the same time recognizing the cultural differences between you and the user. The process of user analysis involves asking questions and determining how the answers should be applied to the design of manuals and help systems. The following items describe the questions to address throughout a user analysis.

1. Tasks and activities the user will perform. “Learn the activities associated with his or her type of work.” [142] Look for tasks unique to the user’s workplace, tasks that require more than one software program and/or information from data resources, and tasks that require communication with other people.
   
2. User’s information needs. Expand the analysis into other work activities and roles users must participate. Find out what information the user needs, origin of information used (Internet, databases, trade magazines, etc.), and how the user communicates.
   
3. User’s work motivations. Try to tap into how software is used to help satisfy work motivations. According to Barker, “what motivates users professionally will also motivate them to do well with software—to assemble interface elements and basic operations into meaningful sequences leading to an objective.” [147] Tables 5.14 identifies sources of workplace motivation, and Table 5.15 suggests how to employ the motivational information in manuals.
   
4. Level of the user’s computer experience. Users bring a wide range of computer experience to each new program and so require different levels of support.
   
   The novice computer user typically experiences anxiety with new technology and is generally distrustful of manuals. The novice user would prefer to be told what keys to press rather than self-exploration of the program.
   
   Experienced users view software as a tool and have definite preferences as to how they want to learn new skills and programs. The experienced user understand the value of manuals and use online help systems more readily.
   
   Expert users often work in the software industry, so they are confident with technology and can troubleshoot effectively. Expert users learn new programs easily but will consult a manual or online help.
   
   Table 5.16 describes each of the three types of users and generalizations about documentation preferences of each type.
   
5. User’s knowledge of the program’s subject matter. The level of knowledge a user has about the subject matter of a program will determine how much background information to supply in the program. For instance, an accountant would probably need less background information for a tax program than the first-time tax preparer.
   
6. User community. Within organizations some type of official group (who Barker labels a community) forms whose purpose is to support software issues. User analysis should “investigate two things: the user groups that your users already participate in and your user’s willingness to join groups for mutual support.” [153] Examples of user communities include help forums, special interest groups, newsgroups, user groups, and web resources.
   
7. User’s learning preference. How does your user prefer to develop expertise with the new software? Generally, a user will learn with the help of an instructor, learn with the help of a manual, or learn through the computer. Consider how computer experience will determine learning mode. For instance, a novice computer user will more than likely prefer to be taught by an instructor rather than use a manual or computer assistance.
   
8. User’s usage pattern. “Usage pattern refers to the interaction of users with programs over time.” [164] In other words, how many features does a user learn or regularly use when using new software. Three main usage patterns exist: regular, intermittent, and casual usage. Knowing the usage pattern assists in developing better manuals and help.

Hood/Carlson

Article Summary of Steven Katz’ “The Ethic of Expediency”

This article began as a conference paper and was initially published in the Journal of Business and Technical Communication in 1993. Katz begins with a citation of Cicero, which points out the power of rhetoric and the importance of ethics as well as the danger when rhetoricians lack ethical conscience.

Next, Katz uses a real-life example of what happens when a writer of a technical document lacks any ethical conscience: he prints a memo that was written in 1945 by a SS soldier to his superior. The memo holds factual information about “load” capacity and transportation. Only a reader with supporting information would be able to find out that with “load” the author is referring to Jews, homosexuals and Gypsies being transported to a Concentration Camp (CC). The memo is written in a detached, sterile and cold way, describing the inhumane transportation conditions in a way that the reader might consider “load” being wood, rocks or anything without life. Shockingly, the recipient of the memo knew exactly what the author referred to with “load”. At no point within the memo, the author has to define that word, even though it is key to the memo’s functionality.

The Final Solution: An Ethical Problem in Rhetoric

In his article, Katz begins to provide necessary background information about the memo to the reader. He further evaluates the memo as a technical document for its clarity, format, argumentation and style. Katz points out that the memo is written in a concise technical format, with a clear purpose statement and ends with a proper recommendation of how to solve the issue at hand. This clearly demonstrates a logical layout of the document. However, the problem with the memo is that the writer shows little concern that his memo’s additional purpose is to transport humans to a CC for torture and death. While the document exhibits excellence in rhetoric, it is devoid of ethos. The expediency of the document becomes more important that the ethical aspect of its purpose. Katz calls it “the ethic of expediency”. The writer of the document didn’t question the need or purpose of the document; he merely functioned as a bureaucrat, fulfilling his duty.

Katz points out that each writer needs to adopt the ethos of the organization he/she works for in order to perform well (198). This theory would then explain the development in Nazi Germany, where the entire nation adopted the ethos of Nazi bureaucracy. Katz develops his theory further by arguing that the ethics of expediency are rooted in Aristotle’s Rhetoric and Nicomachean Ethics. Katz points out that there are dangers associated with rhetoric that is grounded solely on the ethics of expediency.

Ethics in Deliberative Discourse: Expediency

Objectivity in technical writing is a requirement; however, it becomes difficult when one adds the ethical aspect to it. Katz tries to define the role of ethical decision-making in technical communication by describing the role of ethos in rhetoric. Thus, ethics becomes an important component in deliberative rhetoric. Being objective as a technical writer should not equal being devoid of any human component while creating the document. Technical writing needs to be based “on deliberative rhetoric from the standpoint of both rhetoric and ethics” (199).
The definitions of “virtue”, “moral wrong /right” and “truth” are important for technical writers. However, if “right” and “wrong” is subject to interpretation, then the term becomes subjective and no longer fits the need of objectivity in technical writing. Applying this in the most extreme case, Aristotle’s “utility is a good thing” would support the ethics of expediency and put the functionality of the document above its content (200).

Hitler’s “Ethical” Program?

Katz further examines Hitler’s writings and his philosophy and points out the basis of Hitler’s successful application of his philosophies: “For Hitler, as for Aristotle- at least in his discussion of deliberative rhetoric-there seems to be no distinction between “practical wisdom” and “moral virtue”, between expediency and the good, as long as rhetoric serves its end, that is, the State.” (202). Hitler also used science and technology as moral expedients and created a “new philosophy” for an entire nation; he was able to create a sense of urgency as well as creating “common” goals “for the sake of technology”. Efficiency, excellence and elegance in killing became a goal for all followers.

The Technological Ethos and Nazi Rhetoric

Katz tried to define the ethos of technology; becoming part of the culture, technology also “becomes both a means and an end in itself.” (204). In industrial capitalism, value is measured in terms of technical criteria, use, efficiency, speed, productivity and usefulness while social customs, values and beliefs become less and less important. This may be because ethical values cannot be measured and are difficult to define.

Katz analyzes Hitler’s means of propaganda and explains its success: Hitler used rhetoric as a technological instrument to capture the masses and use them to execute his will. Furthermore, his propaganda also becomes a means of justifying his actions. Katz points out that the major reason for writing about this topic is to understand the essential relationship between rhetoric and ethics.(206)

Expediency in Technological Capitalism: the “Final Problem” For Us

What does this article mean for us in today’s culture? In order to prevent the history from repeating itself, people need to understand the importance of ethos and the dangers of pure economic expediency and personal happiness above wellbeing of others. Katz calls scholars, teachers and writers to contribute to a better understanding of the role of ethics and its importance in technical writing. He believes that the awareness for ethical decision-making can be taught and should become a state of mind that can be then utilized within society.

Final Question for Reader from Lance and Vanda:

We want to challenge you to think about and maybe even answer this question:
Can you think of other situations where expediency took precedence over ethics? (e.g. a company would rather pay legal penalties that resulted from a particular defect rather than fixing the problem in the first place).

Thank you for reading this summary! Lance and Vanda

Campbell, Chapter 5: Is There a Certain Format I Should Use?

There is no answer for the best format for policies and procedures. It depends on a number of things.

Beginning to Determine Format
The format depends on your audience, material, and management. However, if you are writing policies and procedures for an outside licensing, accreditation, or regulatory body, you may not have a format choice.

Format and Audience: Figure out who your audience is because certain formats work better for certain audiences (i.e. flowcharts for engineers).

Format and Material: Your information should narrow your format options (i.e. safety procedures require absolute clarity, therefore, your format should be clear, distinct, and make the material easily understandable). The Format Options Chart (5-1) gives general guidelines for which formats to use with which types of material).

Format and Management: If you want a format that management is not comfortable with, make sure to explain it and present your reasons for choosing it.

Deciding on Page Layout
The page layout gives readers basic information about the policy or procedure, such as title, number, or effective date; it also identifies information that is critical to proper use. The amount and types of information you standardize in your page layout is up to you. The goal is to keep it simple so the standardized information that doesn’t detract attention from the policy or procedure itself. Readers should be able to scan the page layout quickly, and then focus immediately on the body of the text.

Choosing Among Format Options
Once you decided on page layout, you need to choose a format for the main text. You have several options: narrative, outline, playscript, or flowchart. You also have secondary format options: question and answer, troubleshooting, matrix table, and list. Once you choose a primary format, you need to use it throughout your document.

Using Primary Formats
The following are brief descriptions of primary formats, which are the mainstay of the document.

Narrative: standard sentence-and-paragraph style. Usually single column of unbroken print running from left to right on page. Two-column formats are also common. Used more often for policies than procedures. Not effective with complex, difficult, or lengthy material.

Outline: variation of standard narrative. Text is separated into distinctly shorter sections and subsections, all labeled. Section identified with numbers, letters, or an alphanumeric combination. Can be used widely. Used in both policies and procedures. Logical and easy to follow.

Playscript: Excellent for procedures that involve more than one person or department. In its simplest form, playscript has two columns. The first column tells who’s responsible, and the second describes what’s required. The steps in the second column are in sequence. This form can be adapted. Playscripting’s visual clarity makes it remarkably fast and easy to find information. Highly recommended for any procedure with more than on actor or responsible party. Not appropriate for policies.

Flowchart: a diagram of a process, which uses symbols and arrows to indicate flow and action. Commonly used in procedures than in policies, but can be used in either. Danger of flowcharts is that they can become cluttered and hard to read.

Using the Secondary Formats
Secondary formats are those that are used as inserts inside the primary format. They can stand on their own as primary formats in some highly specialized documents. There are four secondary formats: question and answer, troubleshooting (or help), matrix table, and lists. These formats summarize, clarify, or expand, on the information in the body of the text.

Question and Answer: used in both policies and procedures. Address items that are particular concern to readers. Sections simulate a personal conversation-worded informally. Good places to address the concerns you know readers have about the policies and procedures.

Troubleshooting: also called help sections and sometimes reference sections. Used primarily in procedures. Deal with breakdowns or exceptions. Often presented in chart format, where each problem is listed individually along with solution.

Matrix Table: connect one variable to a second variable. Excellent format to use when readers need to refer repeatedly to the information periodically over time. Eliminates the need for constant rereading and searching. Have wide application.

List: lists break the denseness of the printed page and let the eye skim quickly. Reader gets impression of information relatively easy to grasp and use. Main purpose is to shorten, organize, and clarity.

Combing Formats
All different formats are often combined and these combinations can be very effective. However, do not randomly or excessively change formats, because this can create a consistency problem.

Experiments and Hybrids
None of these formats is sacrosanct. Experiment with them, modify them, and adapt them to your needs. You can combine virtually any format option with any other option.

Thanks for reading our chapter summary! Gary and Jennifer

What's Technical about Technical Writing

Chapter 8: What’s Technical About Technical Writing?
by David N. Dobrin

Team 2: Gary Teagarden and Jennifer Bruns



David Dobrin, the author of this article not happy with an over-simplified definition of technical writing—“Technical writing is writing about technology.” In the introduction of this essay Dobrin notes that he wanted something more about what technical writers do. “And what they do is write or ghostwrite manuals and reports.”

Observes Dobrin: “The reports and manuals appear when there is a technology, a writer, and readers who want to use the technology. When the pieces succeed, they act as a kind of semipermeable membrane that lets understanding leak through at a controlled rate.”

Dobrin trys to come to a more refined, all encompassing definition of technical writing. He looked at pioneering work of several academics in trying to construct a definition: Fred MacIntosh, John Walter, Patrick Kelley and Roger Masse. For example, Kelley and Masse state, “Technical writing is writing about a subject in the pure sciences in which the writer informs the reader through an objective presentation of the facts.”

Writing Technically

“The definers of ‘technical writing’ look at texts; the definers of ‘writing technically’ look at the encounter which produces the texts.” John Harris defines technical writing: “Technical writing is the rhetoric of the scientific method.” In quoting another expert in Earl Britton, Dobrin writes that not only must writing be objective, it must be univocal. That is, “The primary, though certainly not the sole, characteristic of technical and scientific writing lies in the effort of the author to convey one meaning and only one meaning in what he says.

Britton explains that writing is like music. If one wants complexity in music, one writes a symphony. If one wants to wake up soldiers, one plays reveille on a bugle. Literature is the symphony; technical writing is the bugle call.

Dobrin: “The technical writer speaks with the care of a scientist, the humility of a saint, and the clarity of the bugle call.” Talk about an apt metaphor.

Sections within this piece speak of univocality—precise language and only one meaning to the copy in question. More theory is discussed when he discusses the universalist view of language and the monadist view. The nuances of these definitions are confusing and must be read carefully to grasp the differences. Those taking the universalist view believe a sentence can mean a particular thing and that precisely that meaning can be understood. The monadist alternative is to see language as it is actually used, rather than as a formal system.

A New Definition of Technical Writing

After a thorough discussion, Dobrin notes “Technical writing is writing that accommodates technology to the user.” People do not read technical writing for fun, but because they need to do a task. Technical writing gives what is useful, not what is unknown.

He finishes his piece with a take on how people end up in technical writing—typically from two paths: Technicians who learn how to write and writers who learn to excel at technology. Which are you?

Essay 9

The Social Perspective and Professional Communication: Diversity and Directions in Research

Charlotte Thralls and Nancy Roundy Blyler
This article was written in 1993 for Professional Communication: The Social Perspective. Thralls states that it gives newcomers in the field a sense of the “enormous impact” “the social turn” (quotes in original) had on professional communication research. It also provides a starting point for comparing research trends in the early phases of “the social turn” with the later evolution of those trends (125).

With the rejection of positivism, where knowledge is a direct apprehension of reality, reality is now unknowable apart from language. Language and culture are intimately related; and the importance of the communal and local are emphasized, leading to the centrality of socially mediated meaning and interpretation. Current theoretical movements at this time included poststructuralism, radical feminism, and the philosophy and sociology of science.

The purposes of this article are twofold:
1) Describe the three different and sometimes competing theoretical approaches within the social perspective (social constructionist, ideologic, and paralogic hermeneutic),
2) Use the three approaches to conceptualize important patterns and differences emerging in studies of professional writing.

Each of the three approaches are examined using the four concepts of community, knowledge and consensus, discourse conventions, and collaboration.

Social Constructionist
According to this approach, knowledge is not “individual, internal, and mental” (127), but rather is social in nature. It focuses on community and views “communal entities as the sources of knowledge maintained by consensual agreement; as the repositories of discourse conventions by which communities are defined and shaped; and as the bodies to which nonmembers must—through collaboration—be acculturated” (131).

Community
The concept of community is central to the social constructionist theory because communal entities are sources of knowledge. There is a presupposition of like-mindedness on the part of community members, although even within this approach there is disagreement over the definition of community. Central to this part of the approach is the idea that communities shape discourse and vice versa. Researchers have been particularly interested in the normative aspect of community, particularly on the way these regulate discursive practices.

Knowledge and Consensus
According to Bruffee, one of the theorists most cited in the portion on the social constructionist approach, knowledge results from a community’s consensus about what it will call true; Bruffee terms this consensual knowledge socially-justified belief. This concept has influenced research in the field because it has shifted attention away from universals ensuring truth to the means by which beliefs are incorporated into a community’s knowledge store.

Discourse Conventions
According to Bruffee, communities are constituted by the language its members use. Discourse conventions are indices of community member ship and have a regulatory effect. The simplest form research in this area has taken has been to study the conventions that identify various communities. Because discourse conventions are so closely tied to communities and member ship in them, constructionists have stressed how nonmembers can internalize community norms and language to acquire membership; Bruffee focused specifically on collaboration as a means to this end.

Collaboration
According to constructionists, collaboration the social process implicit in all writing as well as a pedagogic tool for teaching writing; writing is a “communal and collaborative act” (130). Research in this area has focused on how collaborative writing projects can assist in the acculturation of students to their academic disciplines and professions.


The Ideologic Approach
With this approach comes the thought of power and responsibilities of indivduals to challenge established institutional order. Scholars taking this approach wish to extend social inquiry to include the ideologic frameworks that shape language practices with thought and identifies within professional communities.

Community
The ideologic likes to think that academic and corporate communities are powerful mechanisms of reproductive ideoogy. Some feminists critics scrutinize the way academic and business communities reproduce sexism and hierarchical social arrangements. One last thought is a leftist critique of community is leading researchers to a more self-conscious examination of the larger cultural.

Knowledge and Consensus
An ideologic critique on consensus has important implications for research and pedagogy in professional communication. Knowledge and its means of production are distributed in an unequal, exclusionary social order and embedded in hierarchical relations of power (some interests are suppressed while others comminute). The ideologic approach also redirects the analysis of discourse conventions because, if consensus is the production apparatus for reproducing communal values, discourse conventions reflect and reify that consensus.

Discourse and Conventions
The ideologic identifies discourse conventions as complex semiotic systems or symbolic orders that signify and sustain the relations of power implicit in consensual knowledge. There is one more worry and that is neutral discourse elements can mask ideology.

Collaboration
Scholars argue that collaboration should demonstrate to students not merely that knowledge is socially constructed and collaborative activities should also "change the social character of production". Collaborative pedagogy, the power might be distributed more equitably among students in collaborative groups and between students and teachers in technical and business writing classrooms.

Summary of Ideologic Approach
The ideologic approach is one of the ages and has been around for many years, just different ways. There will always be the fine line between language practices in the professional communities. Once they figure out the balance of power in all fields it will benefit all. Wells study says it all with an ideologic approach to knowlege and consensus is directing attention away for constructionists' notions of this concept as indicating agreement among community members and toward the relations ofpower that authorize some knowledge claims and exclude othiers.

The Paralogic Hermeneutic Approach
The name of this approach comes from concern with the interpretive or hermeneutic act and as other approaches it is concerned with social negotiation of meaning. The paralogic hermeneutic theorists claim that all interpretation and understanding come out of communicative interaction (Thralls & Blyler, 1993, p. 136).

This approach is fundamentally different from the social constructionist and ideologic approaches discussed previously.

Community
The social constructionists look at the community members as people who share commonalities in their beliefs and language use, as well as interpret and attach meanings to their experiences within interactions of the community. The argument of paralogic hermeneutic theorists is that despite belonging to certain communities, we have a variety of beliefs and statements that we regard as true besides the ones that are preferred in our communities and we also understand others who live in different communities.

The paralogic hermeneutic theorists redefine the concept of community by brining focus on the interaction experiences of each communicant. Emphasis is primarily on communication and the meaning it creates for each participant.

Knowledge and Consensus
The paralogic hermeneutic theorists also disagree with social constructionists’ understanding of knowledge and consensus. According to the paralogic hermeneutics approach, each participant engages in so called hermeneutic guessing until they arrive at the understating of other interactant’s values, beliefs and language use. During the hermeneutic guessing, interactants use concepts of “prior” and “passing”; “prior” is assumption about the interactant and his/her beliefs, values and language-use, and “passing” is adjustment to prior assumptions as they continue the interaction. Consensus in this case is when two interactants share passing theory; however, the consensus is always temporary and will need readjustment next time they communicate.

Discourse Conventions
The paralogic hermeneutic approach again opposes the other two theories on how we communicate. “Paralogic theorists claim that the discourse conventions derive meaning from their use by communicants (Kent, 1989)” (Thralls & Blyler, 1993, p. 138). Essentially according to this theory, meaning is in people, not in words.

Communicators try to match their beliefs about the language use to the beliefs of others, share those beliefs and reach agreement. Paralogic theorists state that discourse conventions should never be equated with effective communication, but only used in combination with valuable background knowledge and perceptive hermeneutic guessing in each interaction.

Collaboration
The interpretive or hermeneutic act is fundamentally collaborative; therefore, the paralogic theorists agree that the interpretive act should be the focus in writing pedagogy. The paralogic hermeneutic approach suggests to look at the writing as an accommodative activity and to transform the classroom into a one-on-one student/teacher collaborative environment. This further suggests rethinking the purpose of many collaborative activities presently used in a writing classroom. Theory also emphasizes that group members cannot base their writing on a set of rules that will produce an effective document. These conventions could be used as a useful background knowledge (previous experience with writing similar documents) only.

Summary of the paralogic hermeneutic approach
The paralogic hermeneutic approach represents a very different look at professional communication. It differs from the social constructionist and ideologic approaches on fundamental issues of interpretation and communication emphasizing the external and uncodifiable (non-systematic) nature of communication process.

Assessment and Directions for Future Research
The social constructionist theory has contributed a lot to the field of professional communication studies. As a result there is a widened research agenda in professional communication that includes qualitative and quantitative studies of the organizational and classroom contexts in which writing occur (Thralls & Blyler, 1993, p. 141).

The social constructionist theory has also helped to establish professional communication within a larger field of cultural studies thus linking professional communication to other disciplines.
Ideologic and paralogic hermeneutic approaches have contributed to the discussions of social theory consequently deepening our understanding of communication as a socially based activity. Both approaches also encouraged us to scrutinize some of the constructionist claims and their implications. The ideologic and paralogic hermeneutic approaches offer important and dramatic directions of future professional communication research.

Summary of Barker, Chapter 4

Introduction
Reference documentation, or support documentation, are the look-up and help parts of a manual. They should be organized in a task-oriented manner, not just alphabetically. When designing reference documentation, it is important to consider the correct form and organization method, as well as the user's needs.

Choose the right form of reference
Different forms of reference documentation include appendices, Readme files, job aids, and innovative forms.

Appendices are sections of a manual containing detailed, technical information. Sections may include error messages, filenames, troubleshooting tips, compatibility information, key combination charts,printer driver charts, or frequently asked questions.

Readme files are text documents containing important initial information, including installation details or tips, information updated or added after the manual was created, new features in an updated program, revision histories, errors, file descriptions, content of directories, and compatibility requirements.

Job aids, or job performance aids, are shortened documentation that help users with basic knowledge to perform tasks more efficiently. Job aids may include keyboard templates, cheat sheets, laminated overview cards, or quick reference cards.

Innovative forms are documentation that are presented in special formats, such as foldouts, posters, and flipcards. The advantages of special formats like flipcards are that they improve readability, contain a lot of information, make information more accessible, and use elements like color to help locate information.

Decide what to include
Reference documentation should include three types of content: commands, interface elements, and terminology.

Commands are the instructions used to work with a program. These include meanings of special function groups, explanations of set commands, definitions of format commands, instructions for using utilities, explanations of toolbars, and definitions of macros.

Interface elements are parts of the screen that are used to interact with the program. Information aobut interface elements may include explanations of menus, definitions of keys, labels of screen regions, and explanations of rulers.

A glossary defines terms used in the manual. Glossaries may defines terms that relate to the software itself or to the subject addressed by the software.

When developing reference documentation, writers should also consider the content to include in each reference entry. They may include conceptual information, structural information, how-to information, or technical information. Conceptual information explains the term and its function. Structural information explains how the term relates to other terms. Technical information describes the programming information related to the command. The content of each reference entry should be based upon the user's needs.

Establish a pattern
Whatever the content of reference entries, the same pattern should be used for each entry. This helps the user to become familiar with the format. Topics included in patterns of reference entries include definitions, explanations, examples, step-by-step directions, and warnings.

Organize the reference section
Decide what organization to use on your own. Make sure to decide something that supports the overall task orientation of the manual. There are two basic choices to use to accomplish this: alphabetical and menu-by-menu.

Alphabetical
This format divides the commands into groups based on the beginning letter of the command, in alphabetical order. You can choose to do this by specific term, or by sections of commands. However, if you choose the latter option, the question becomes how to organize the sections: simple-to-complex or more abstract and concept-oriented.

Glossaries are a type of alphabetical reference, which users appreciate because of the virtue of predictability. Using a glossary emphasizes features over functionality. The glossary also helps the writer by helping to make sure all the features are explained.

Unfortunately, the drawbacks for alphabetical organization outweigh the advantages; the main drawback being that the format doesn’t support the task orientation of the manual.

Menu-by-Menu
This format sets up the references by menus. This allows the writer to arrange the documentation as it appears on the main screen or the menu bar. The organization is almost self-explanatory: a main menu, secondary menu, etc. This format provides a reinforcement of the task orientation between the documentation and the screen.

Show how to use the reference information
In most cases, the reference information shouldn’t include information on how to use it. With multiple, elements, however, the user should be shown the path the writer intends to follow. Usually, this is done with an introductory paragraph that states:

• Who should use the information
• How the writer organized the information
• Elements of each entry
• Relations to other sections of the document

Discussion
Reference documentation is designed to function on the support level of task orientation. There is very little “how-to” information included in this type of documentation. In fact, reference documentation establishes the least engaging relationship with the user.

Understanding the reference user
Reference users do not like to waste time looking things up in help functions or manuals. They also dislike having to leave a screen to search for their information. Well-designed documents will cater to the values of efficiency and immediate usability for these users. As a writer, be sure to establish a pattern and follow it. A good rule to follow: generally, the more structure there is in the information, the more usable the entries are within the document.

Understanding a reference entry
As the writer, look at the idea behind the repeated categories, column heads, or other user-oriented reference elements. These work for the user because each one answers a question the user might have about a function or command. Keep in mind that the elements of a reference entry respond to the needs of the reference user. Each entry should have the following:

• Access information
• Function definition
• Associated commands
• Qualifications/special cases
• Tips

Try to answer these questions for the reference user:

1. How do I get to the function?
2. What does the function do?
3. What other commands do I need to know about?
4. When can I use the function?
5. How do I use the function well?

These elements should do much of the work of establishing the task orientation of a manual.

Please check pages 112-113 for a checklist to evaluate efficiency for a reference document.

(Submitted by Team 1: Beeman/Xiong)

Summary of Chapter 4: What’s the Best Way to Word This?

Chapter 4 provides a good checklist for the document writer when making decisions that should keep the document clear and concise. Campbell offers a cookie-cutter approach with checklists (4-1), numbered lists (4-1 cont’d) and columns (4-11).

She introduces some basic rules and explains the differences between technical and narrative writing. The most important thing to remember as a technical writer is to keep the document concise and clear in order to develop a successful document. Campbell lays out the evolution of writing rules (from “fancy and bulky” to “simple is good.”) and recommends that technical writers cut out any unnecessary verbiage, whenever possible.

There are several things to consider when one is trying to cut down on superfluous words:

• Cut out any words that are redundant and be frugal and concise with word usage
• Avoid pompous, stuffy language
• Write as you would speak to the reader
• Use active voice and present tense.

However, don’t change the meaning of the sentence by taking out words. In order to replace long, redundant words with concise ones, the writer should have a good vocabulary and follow these guidelines (Campbell, p.90ff):

• Say what you mean and mean what you say
• Use specific language
• Be consistent
• Remain correct
• Consider the reader
  o Don’t assume anything
  o Look at the reader’s experience
  o Use jargon carefully
  o Distinguish between users and readers
  o Calculate reading level (see how on p. 124)
  o Word documents carefully.

Campbell suggests that the author use active voice and present tense; in addition, the voice and tense should remain consistent throughout the entire document to maintain clarity and conciseness. The author should avoid using vague terms such as sometimes or the overuse of empty phrases to fill the page.
The author should always remember to keep his/her audience in mind and write at the appropriate reading level. Also, when reading out loud, the document should sound just like spoken words. Campbell provides a list of wordy and redundant phrases (p.115f) and pairs them up with clear and precise alternatives.

One should develop a list of favorite transition phrases, but also be careful to not overuse the same ones. Some transition words are: “also, finally, but, still, as, since…” (p.117). Campbell also provides a list of common problem words that are used in a wrong context sometimes (p.118f).
A more serious and common issue is the misplacement of words within a sentence. Misplacement of words can alter the meaning of the entire sentence, which could be devastating in a procedure. The word “only” is extra tricky and has to be placed with caution at the desired location to highlight the proper word(s).

Campbell offers some practical solutions to alleviate the issue of misplaced words: the author should

• use the S-V-O structure
• break the sentences down into short sentences that begin with an action verb
• keep it simple by using short and easy words
• be very specific and “to the point”, avoiding redundancies or jargon as well as negative wording, “turn off” phrases or misplacement of words.

It’s also a good idea to start a sentence with an action verb and to use one action per step within a procedure. Next, the writer should assign the action to the doer (=subject) and structure the sentence in a way that the most important information is at the beginning and at the end of the sentence. Finally, the writer should choose the right format that is clear and concise.