Barker Chapter 12 - Getting the Language Right

In this chapter, Barker discusses the role language plays in helping the manual and help system attain the goal of supporting information-oriented work. He begins this discussion my noting the ways we process information and that there are two central difficulties that many problems in the language of software documentation revolve around: failure to write so that the user can perform the task easily, and failure to write as if we were speaking to real human beings.

Next, Barker provides a list of guidelines for ensuring that your style is oriented to users’ needs.

Write About Actions Rather Than Functions
Instead of simply giving a definition of the function, you should answer the question of “Why would I want to perform this function?” If you identify the object and tell the read what to do with the object, you are creating a set of tools to help the user do their work.

Revise for the Active Voice
Passive voice makes a passage seem impersonal, which will make the reader feel manipulated uncaringly. Active voice is more personal and direct, which makes the reader feel empowered.

Revise to Keep Writing Simple
You don’t want your reader to waste time rereading sentences, so try to make passages simple. Simplicity helps every aspect of software manual writing and you should strive for simplicity in each sentence.

Revise to Build Parallel Structures
Parallel items acknowledge the similarities between concepts and express that similarity in matching grammatical structures. This is one of the best solutions to the problem of using the user’s short-term memory effectively by helping readers remember even though they may not recognize the pattern.

Add Operational Overviews
Because users often read for meaning, you should provide prose passages containing clear overviews of concepts as well as straight procedures; users appreciated learning the conceptual model of the program and how the program does its processing (389).

Barker then begins a discussion about language, learning, and how to effectively present information in software documentation.

How Do We Process Language?
Barker writes that to set goals of language use to support task orientation, you must first look at how readers process language. He notes that the act of reading requires that the concept in the reader’s mind bond with words on the page and that the words register as significant, which is meaning. The words don’t convey meaning to the reader, but the reader brings meaning to the words. The more clearly writers can anticipate that task the more task-oriented the manual.

Performance-Oriented Language
Performance oriented software documentation is when there are clear explanations of how to perform using the software. Using the active voice, using the ‘you’ pronoun, and using the imperative verb add to the performance orientation of the style. You should write to an actual human being, which will make the documentation less stuffy, formal and robot-like.

How Do We Remember and Learn?
After finding the right answer, users must remember the idea until they get back to work. This means that the writer must rely on both short and long-term memory. You should strive for a style of writing that has words that connect to the users’ mind, which will make it easier to remember. To do this, you must structure the sentences carefully using the following sentences: patterned, highly parallel, balanced, and sentences that end in three rhythmic clauses.

Style Problems in Software Documentation
Barker writes that problems with style in software documentation relate directly to your overall goal of making software easy to use. He then provides some of the problems associated with writing in software documentation.

• Acronyms: Users can often understand common acronyms such as DOS and RAM, but the difficulty comes when some of the terms constructed as part of the computer program or system appear in the document. You can’t always avoid acronyms and abbreviations, but try to use a few of them in a sentence at a time.

• Synonyms: You should use these consistently and accurately as to not confuse the user. You should also try to use the terms that users will most likely recognize and build in crossover techniques, such as synonyms in parentheses.

• Paragraphs and Sentences Too Long: Paragraphs should focus on explanations, not performance, and not on steps telling the reader what to do. It is best if the writer can forget about paragraphs and just think in terms of lists and chunks of no more than three sentences.

• Emphasizing the Computer Instead of the Program: A writer must remember that a computer doesn’t perform tasks, the program does. When writing software documentation, you must think about the program performing the functions, which will also help promote the program.

• No Connection between the Heading and the Topic: Often, in a manual, headings are following by paragraphs explaining a program. However, the information in these passages doesn’t always match the heading. Instead, the writer has included one or two relevant details about the program, which get presented in a highly technical language.

• Too Formal Tone: Software documentation is intended for real people, so it shouldn’t be too formal. According to Barker, speaking in a informal tone—without being overly familiar or presumptuous—makes contact more quickly and evokes the user’s desire to do well on the job. You can incorporate an informal tone into your writing by using the following characteristics: use of contractions, reference to other users, and humorous aside.

• When to Use Humor: Barker writes that humor sparks as much controversy as it does good feeling in manual writing. Bad humor can cause a user to reject a manual. Common sense tells us that humor will not work in all kinds of documentation, especially sections where the user simply looks up information. You should always test humor before the final draft.

• Ambiguous Task Names: In task-oriented documentation you should name tasks clearly, with a sense of planning for the user’s new vocabulary. Don’t fall into the tendency of referring to tasks vaguely because this leaves the user with more questions.

• Step Not a Step: The step constitutes the basic element of human-computer interaction, so you should make sure that each step is actually a step and not just a guide or information about the previous/next step.

• Omitted Articles: Barker ends the chapter by discussing the tendency for software documentation to fall into the telegram style of writing. We don’t have to pay for words anymore, and such attempts to leave out articles to sound official fall flat. Since you are communicating with real people, you should use real language.

We're Thinking About Going On-Line

Campbell Chapter 12

In this chapter Campbell discusses putting policies and procedures online. She mentions that going online doesn’t change your policies or procedures it simply creates another method of communication beside written or verbal. She mentions the advantages and disadvantages of going online.

Advantages:

• Faster retrieval and faster circulation
• No paper revisions
• Easy storage
• Can link related facts or documents together in a way that gives users faster access.
• Easy access to the manual
• Fewer deadlines
  

Disadvantages:

• May intimidate users who are not computer literate
• Could by costly (software, hardware, etc.)
• Need for training
• Format limitations
• Lower readability
• Some users may not have access to retrieve document from a computer
• Reading from a screen is not always preferred
  

Campbell mentions that there are certain questions the writer should ask about the user:

• How experienced and comfortable are users with computers?
• What kind of equipment do they have?
• What kind of software do they have?
• Do they have read access to a terminal
• What format are they used to working with and do they prefer?
• What’s their environment like?
• Are their organizations supportive
• Will they really check the system regularly for updates?
• How can they be made to acknowledge receipt?
  

Designing an On-Line System

In this section Campbell discusses being aware of the limitation online documentation creates. Knowing what the user is reading from meaning what kind of computer screen they have and that it is harder to read on screen than on paper. She mentions four factors to keep in mind while designing:

1. Visual simplicity
2. Ease of use
3. Clear operating instructions
4. Adequate conversion of elements such as acknowledgements and revisions

Finally Campbell talks about making sure the users know when the document has been released and when revisions have been made. Most importantly she mentions to make sure the user receives and uses the online policies and procedures.

Gender, Technology, and the History of Technical Communication

In her article “Gender, Technology, and the History of Technical Communication,” Katherine Durack examines the history of the female role in the technical communication field. She begins her discussion by noting the absence of women in the recorded disciplinary past. One possible reason is that “women have contributed only very rarely to technical and scientific work” (36). If this is true, and scientific inquiry and technological innovation have been primarily the work of men, then the contributions of women may have been consequently lost, subsumed, or overlooked. Another possibility is that the absence of women may have been due to historians and not actual historical reality.

A “Peculiar Set of Cultural Blinders”
Although those in the field of technical communication have yet to agree on a single definition, technical writing often contains either or both of two key characteristics: a close relationship to technology, and an understanding that technical writing is associated with work and workplace (36). It follows then that what is understood as technical writing comes from what is considered technology, work and workplace. The assumption is that these terms are gender-neutral, and that addressing the matter of gender and the history of technical communication is as easy as searching for women who have distinguished themselves in scientific, medical and technical fields (37). However, this view is often contested because of its simplistic view that inadequately addresses biases from our past and future.

History and Women’s Work
History, including the history of technical communication, primarily focuses on the works of great men and the great works of men (37). In both of these cases, there is a need to establish significance, which usually involves prerequisite location in the public sphere. This public sphere is male dominated, while the private sphere is generally the realm of women. The activities of women have typically been omitted because history focuses on public and political activities and innovations. To include women’s work in the history of technical communication, “we [must] contest two assumptions that lead to their exclusion from our disciplinary story: First, (the assumption of agency) that women are not significant originators of technical, scientific, or medical achievement; second, (the assumption of technological significance) that women’s tools are not sufficiently technical, nor their work sufficiently important, to warrant study of their supporting texts” (37).

Women as Significant Contributors to Science and Technology
To overcome the first assumption, women need to be identified who have contributed significantly to science, technology and medicine. Then, their written works must be fit into technical communication history. The main difficulty facing the historian is the apparent lack of women’s contribution to these fields. Women, like men have undoubtedly sought means for improving their work processes, but their significance may be obscured by having been misclassified, trivialized, or attributed to men (37). Women’s inventions may have been under-reported because they weren’t ‘real’ inventions of technology such as weapons and machines.
Often, when women did invent ‘real’ inventions, they were left off the patent record. Some reasons for this include: women’s lack of disposable income and time, married women in the United States and Britain could not own their inventions or patents until the Married Women’s Property Acts passed, the necessary technical and mathematical training necessary to build models of inventions and patent them was not available to women, cultural stereotypes discouraged women from taking credit for their achievements, and these same stereotypes encouraged women to be generous, thus sharing ideas instead of profiting from them (38). Technologies that pertain specifically to women’s biological functions and social roles, including the baby bottle and sewing machine, have essentially been ignored by historians (38).

Women as Significant Users of Technology
Addressing the second assumption involves a different strategy: departing from conventional history to challenge existing definition, seeking a “a new narrative” that focuses “on the casual role played by women in their history and on the qualities of women’s experience (39). The industrial revolution brought about great technological innovation and increasing differences about appropriate work roles for men and women. Women are often seen running machinery, but it is rare to see them actually knowing what goes on inside the machine. During World War II, women were expected to help out, but as soon as the men came home, they needed to return to their homes. Even when a woman is skilled at a job, such as sewing, they are often underpaid because it is a ‘woman’s job.’ Men remain predominantly the makers, repairers, designers, and uses of what we typically consider technology, while women hold household jobs, which are unrecognized and generally unpaid (39).

“The periodic submittal (and rejection) of texts such as cookbooks to the Society of Technical Communication’s annual publications competition demonstrates the difficulty we have with considering as ‘work’ a productive activity that is typically assigned to women and accomplished within individual households without benefit of financial compensation” (40). Durack adds that when a man tinkers in his garage it is considered a significant invention, but when a kitchen doubles as a chemistry lab it is often discounted as technological.

The Household as a Setting of Consequence
The current focus of workplace writing as a definition of technical writing fails to recognize the household as either a workplace or a setting of consequence. Writers in organizations are more easily studied and compared, therefore individual household are often excluded. However, there are significant instances of technical writing and use of technical documentation that occur in the household since many products are geared toward home use (40). These include computer hardware, lawn mowers, blenders and credit card agreements. There are many instances in which private individuals must interact by text with organizations (41). Also, many people are starting to move the traditional workplace into their household.

Toward Inclusive Definitions
Durack concludes by writing that “if we are to include the accomplishments of women in the history of technical communication, we must first challenge the dualistic thinking that serves public and private, household and industry, and masculine and feminine labor” (41). She notes that she doesn’t know if it is possible to construct a single definition of technical communication that can accommodate both past and future changes in the meaning and significance of work, workplace and technology, but she offers the following observations.

• Technical writing exists within government and industry, as well as in the intersection between private and public spheres.
• Technical writing has a close relationship to technology.
  
• Technical writing often seeks to make tacit knowledge explicit.
  

She concludes her essay by stating “as we construct the history, a major challenge will be to examine why we deem certain artifacts technology, their attendant activities work, their place of conduct the workplace, and therefore find reason to include associated writings within the corpus history of technical writing” (42).

What’s technical about technical writing?

David N. Dobrin

Dobrin discusses various definitions of technical writing. He refers to common definitions that had been given in the past. He states that some definers choose to define "technical writing" and some define "writing technically"

He first discusses Fred MacIntosh’s method, which is to collect various technical writing pieces and find the characteristics they share.

Jon Walter’s definition includes three pieces:

1. Had specific rhetorical modes and formats which were pitched to specific readers (format).
2. Had a specialized vocabulary and an objective style (style).
3. Had primarily technical content (content).
   

Patrick Kelley and Roger Masse:
Technical writing is writing about a subject in the pure science or the applied sciences in which the writer informs the reader through and objective presentation of facts. (Page 109)
Dobrin states that Walter, Kelley and Masse’s simply define technical writing with other terms that need to be defined.

John Harris:
Technical writing is the rhetoric of the scientific method. (page 109)

Charles Stratton:
A particular art, science discipline, or trade helps audiences approach subjects. (page 110)

Earl Britton:
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. (page 110)

Dobrin explains that Harris and Stratton are objective but Britton adds univocality. Dobrin is trying to stress how linguistically dense technical writing is. However, Britton says it is simple. He states literature is a symphony technical writing is a bugle call. (page 110) meaning you simply state what you want the reader to do. The bugle call tells soldiers to wake up.
Dobrin goes on to discuss the different aspects of defining words and their true meaning. He also makes references to the scientific method, which refers to Harris’ definition.

Formal versus epistemological objectivity
The universalist view often called the "window pane" theory includes ten assumptions:

1. The world is out there.
2. Properly applying our minds, we can know it.
3. There is a best way of knowing the world.
4. The best way of knowing the world is available to any intelligence.
5. It is independent of language and human quirks.
6. Language is a way of using and telling this access.
7. We are able to determine the correct and incorrect uses of language.
8. So distinguishing is difficult we often fail at it.
9. If we can purify language and our consciousness, we can formulate a perfectly correct language, a universal language, which we would not make mistakes.
10. It is our responsibility to do so.

The monodist view
This is to see language as it is actually used. It doesn’t separate language and knowledge also that there can be privileged access to the world.

Alternity
It is a source of vitality and creativity, because it means language is always playing with the possible. (page 117)
In this section Dobrin explains that alternity gives self-expression. Jargon woud fit into this category.

Finally Dobrin give his own definition of technical writing:
Technical writing is writing that accommodates technology to the user.

He refers to technology in this definition as an array of tools or procedures. (page 118)
Dobrin goes on to explain nothing can be simply defined but the best sense of the word n the definition should be carefully chosen.

Campbell Chapter 11 - We Haven't Used That Procedure in Years

Campbell begins her discussion by addressing the importance of keeping documentation up to date. She writes that you should make a commitment from the beginning to establish a clear and regular review process.

When to Revise
Campbell writes that there are numerous opinions about when and how often you should revise, but the best approach is to find a balance between regularly scheduled review and revision and as-need review and revision. The best balance will depend on content factors and logistics.

Campbell then goes on to describe regularly scheduled reviews, stating that the ideal is to review and revise annually. She notes that if this isn’t possible, you should create a realistic schedule and stick to it. Another possible solution is to perform rolling reviews, which are a good way to work regular revisions into a schedule with a minimum of disruption. To perform a rolling review, you schedule different groups of policies and procedures for review periodically, and then as each review is completed, roll another group into the schedule.

Next, Campbell discusses as-needed reviews, which are needed when a significant number of changes have been made to the documents, content changes occur or are pending, and certain types of problems or behaviors increase. A good rule to follow when revising is: if approximately 25 percent of the given policy or procedure has been changed, it’s time for a complete review. Also, anytime you have new equipment, programs or products, you’ll need to adjust your policies and procedures. Finally, you should listen to others around you. If you hear about accidents, complaints, questions, confusion, errors, deviations, rejection rates, and corrective actions, it’s probably time to update.

When Not to Revise
Campbell writes that before you revise a policy or procedure you should first ask “why?” She says that you shouldn’t rush into revision because the policy or procedure may not be broken; it might be the implementation process.

How Much to Revise
According to Campbell, your goal is to change as much as necessary and as little as possible. How much you revise depends on the nature and degree of the changes themselves. Campbell notes that you can change the following: a portion of an individual policy or procedure, all of an individual policy or procedure, a section or related group of policies and procedures, or an entire handbook or manual.

How to Revise
Campbell writes that the revision process is similar to the process you followed in the original development of your policies and procedures. However, you must also take the following steps: Develop a follow-up mentality, Check and double-check related documents and cross-references, create a formal mechanism for users to give feedback, continually solicit information, keep a file for suggestions and ideas, and keep records of all revisions.

How to Clarify the Changes
Next, Campbell writes that you should make it as easy as possible for the user to see what, and how much, has been revised. You can use one or more of the following options: visually highlight the changes on the page, use clear, descriptive wording in your transmittal document, and summarize the changes. You have many choices for highlighting, but the trick is to highlight the changes so that they are immediately obvious to the user. To help the reader see what you’ve changed, use clear words like added, replaced, deleted, modified, etc. The goal is to make it fast and easy for the reader to tell what’s been changed. Also, in the transmittal document, give readers a brief summary of the major changes. You should tell readers: what areas are affected, how extensive the change is, the reason for the change, and the impact on the bottom-line.

How to Hold Users Responsible
To avoid users coming back several months after the revision has been sent saying they never got it, Campbell suggests using a notification system that forces users to share responsibility for updating their document(s). She says the system is easy to construct, and its effectiveness lies in its simplicity. It should contain the following parts:

• Users are given a revision index from which they record all revision notices in the order of receipt.

• All change notices are clearly numbered in an obvious and easy-to-identify manner so that any missing numbers can be spotted immediately.

• Users are instructed that it is their responsibility to record all change notices in their revision indexes and to notify the appropriate person if any are missing.

• A summary of all the change notices issued is periodically sent to users.

Campbell provides an example of one such system. She also notes that some organizations require users to acknowledge in writing that they have received policy and procedure revisions. Finally, she writes that whatever notification system you choose, be sure it makes clear to users that they have obligations in the change process and they will be held accountable for meeting those obligations.

Campbell - Chapter 10 - But That’s Not the Way We’ve Always Done It

Writing Effective Policies and Procedures: A Step-By-Step Resource for Clear Communication

Nancy J. Campbell

Chapter 10 – But That’s Not the Way We’ve Always Done It

Introduction

Despite all your hard work and effort, it’s important to recognize that new policies and procedures often invite resistance.

Don’t Give Up

Change is hard and takes time to process, so start at the beginning and try to avoid getting discouraged.

Dealing With Resistance

Most resistance to change stems from fear. There are many different types of fear. There are also six basic steps that you can take to help users manage the change.

1. Involve
2. Explain
3. Listen
4. Enforce
5. Reinforce
6. Evaluate

Early Communication

Always remember that early communication reduces later resistance. Involving users upfront is the best way to combat negativity. It is better to begin with involvement then to end with it.

Early Detection

Often your users may have been through a similar situation and think it will either fade away or end up to their disadvantage. Use open, honest communication to help address these concerns. Early detection also identifies the biggest resisters, so you’ll know with whom you’ll need to take a firm stand.

Advance Preparation

Consistently involving users in the development process gives them more time and knowledge with which to work through the issues, generally resulting in more cooperative behavior. Forewarned is forearmed.

Continuing Education

Running ideas by users and keeping them updated as to the status of the project will help them to remain stay involved and prevent the process from losing steam. This constant communication with users strengthens your final product.

Final Notice

As long as you have communicated and educated your users continuously throughout the development process, the final notice shouldn’t come as a shock. By acknowledging sensitive issues and honing your listening skills, you can demonstrate respect for their viewpoints. You can also mobilize cooperative users to help encourage wider acceptance of new policies and procedures.

Grace Periods

Grace periods allow for a more gradual transition between the old way of doing things and the new. These are especially useful in cases where there is strong resistance. They provide additional preparation time before full enforcement of the new rules.

How to Use a Grace Period

Using a series of notices helps to keep everyone informed as the date of full enforcement approaches. The first notice might inform users of the impending changes, and state that the rules will be enforced informally for a period of time. The second notice warns of the deadline for full enforcement. The third reminder states that the new rules are in full effect and the disciplinary consequences for breaking them.

Delivering Bad News

When a new policy or procedure is simply downright unpopular, continuous communication throughout the development process remains even more crucial. There are two very important strategies for delivering the bad news.

Preempting

Identify the likely objections that will be raised and begin the communication process by addressing those issues first.

Taking the Heat

It is important that those who enact new policies and procedures take responsibility for them and can defend their position. Again, patience and receptivity is key.

Here Comes Trouble

There are several perceptions that a new policy or procedure may invoke in users that are guaranteed to cause trouble. These include:

• Unfairness
• Negativity
• Hypocrisy
• Pointlessness
• Unworkableness
• Restrictiveness

When the Writer Is the Resister

If you as a writer have objections to a policy or procedure, be sure to deal with your own concerns in the same thoughtful, level-headed way that you would deal with users’. One way is to write down your concerns and frustrations, then write down the reasons for the new rules and the circumstances that are driving them. Be gracious and professional and abide by the organization’s rules.

Conclusion

Campbell concludes her chapter with a summary of its content, and several tools and resources. These include a tip sheet for overcoming resistance, guidelines for delivering bad news, guidelines for generating receptivity, and guidelines on resistance factors.

Robert R. Johnson - Audience Involved: Towards a Participatory Model of Writing

Audience Involved: Towards a Participatory Model of Writing

Robert R. Johnson

Introduction

Johnson begins his article by describing four ways in which technical communicators have responded to criticism that their pedagogy is based solely on the “unreflective use of formats”. These include increased attention to audience, invention, visual meaning, and ethics. Unfortunately, Johnson feels that in developing these ideas, technical communicators have borrowed theory from other disciplines while offering few contributions of their own. By exploring technical communicators’ unique relationship with their users, Johnson hopes to challenge general composition and rhetorical studies with a more reciprocal and participatory model of writing.

Writers and the Hegemony of Authority

The creation of discourse has changed from an individual model to a community model in recent years. This community model can be divided into two common sub-models. The first of these involves a writing process in which a single author produces a text with the planning and revision assistance of a group. The second sub-model involves “plural authors, singular text”, in which multiple authors collaborate throughout the entire production process to produce a single document. Missing from these models of collaboration is a discussion of audience. Historically, audiences have been viewed as either “addressed” – an external object to be acted upon by the text, or “invoked” – a fictional construct of the author’s imagination. Johnson argues for a conception of the “involved” audience, in which the audience participates directly in the production process. His discussion is informed by both the history of technology, and the history of rhetoric.

Technological Knowledge: Some History and Definitions

Technological knowledge can be defined in two ways. The first involves the history of technology, and includes models of technological determinism, science versus technology, and the social construction of technology. The second is grounded in the discipline of rhetoric, where technological knowledge can be categorized as a productive knowledge or art. Under this model, the effectiveness and quality of a product, such as an instructional document, is dependent upon the judgment of the users.

Usability: An Overview

Johnson defines usability as “part of an iterative process that allows users to provide feedback during the conceptual, design and production stages of a product’s developemnt. Usability is beneficial to technical communicators in that it argues for their early inclusion in the development process, helps them to assume a role on the development team (rather than being viewed merely as “scribes who ‘write up’ technical information”), and allows the writers to effectively implement user knowledge into the development process.

Users and Usability Specialists: How They Work Together

Here, Johnson presents two scenarios in which usability specialists collaborated with users to produce improved texts, which he defines as “virtually any symbolic representation that enables humans to interact with technological artifacts”.

In the first scenario, Johnson describes a classroom assignment in which he instructed his students to develop improved documentation for the university’s new voicemail system, which was very poorly documented. Working in teams, the students administered surveys, questionnaires, and interviews to targeted users. This resulted in an impressive amount of feedback. In analyzing this data, it seemed that the situation involved two different forms of knowledge: the knowledge of the developers and the knowledge of the users. Developers viewed the system with a “highly rational, hierarchical view”, while users inhabited a different knowledge space, in which their focus was limited to the object before them and the ways in which they needed to use it. It became the duty of the technical communicators to bridge this gap. The vendor of the phone system was so intrigued by the outcome of this user-writer collaboration that they sent representatives to the university to meet with the students involved in the project.

The second scenario Johnson describes involves usability testing of a computerized interview scheduling system. The graduate students involved in the project made use of “low-fidelity prototyping”, in which a mock-up of the proposed interface is fashioned from paper cut-outs. During a prototyping session, one of the students would play the role of the computer as the student interacted with the subject, manipulating user interface elements in response to the user’s input. This process helped to identify the most intuitive user interface design. Johnson describes this as a “turning of the tables”, that puts “the burden of production on the ingenuity of the programmers to create a usable system”.

Conclusion

Involving users in usability evaluation and testing can help technical communicators make design decisions. It may also foster increased user-awareness among system developers. Creating effective systems requires that users be allowed to participate along with writers and developers in the production process.

This involved audience model also has ramifications for the wider field of composition studies. Involving an intended audience in the writing process can have interesting effects on a writer’s conception of what they are producing. Johnson lists several ideas for activities and experiments that would bring the audience into the composition classroom. The learning potential under such an arrangement is endless.