English477577Fall2007courseblog

Howard - Who “Owns” Electronic Texts?

2007-12-08T19:17:00.000-06:00

Who “Owns” Electronic Texts?

Tharon W. Howard

Introduction

In his article, “Who ‘Owns’ Electronic Texts?”, Tharon W. Howard explores intellectual property law from a historic and philosophical perspective to better understand how notions of copyright are being challenged by current advances in mass communication technologies. Most writers, he states, tend to believe that authors “own” their texts, and can assert control over how they are used. The trend toward collaborative writing processes and online distribution of texts has raised many intellectual property issues that writers are unprepared to deal with.

Howard then presents five potential scenarios illustrating the intellectual property dilemmas that modern writers face.

Scenario 1 involves a company that would like to incorporate a famous photograph located in a popular magazine into the cover of their annual report. How should the document designer proceed?

Scenario 2 imagines an individual being asked to install a piece of software on their work computer, even though it has already been installed elsewhere.

Scenario 3 questions if one can legally and ethically quote from an email message posted to a listserv in a scholarly article. Is this an obligation, and who controls such a text?

Scenario 4 explores whether a personal correspondence between individuals via a company email system should be considered private. The computers are owned by the company, but does that give other employees the right to monitor and reproduce such personal messages?

Scenario 5 describes a faculty member compiling a list of hyperlinks to potential employers’ job listings for job-seeking students. If these businesses are derived from a published book of business listings, does the creator have an obligation to pay royalties if their hyperlink system is published?

These scenarios, state Howard, reveal the way in which intellectual property issues are becoming an increasingly large concern in the workplace. In fact, an understanding of intellectual property and copyright in this environment could very well be considered a necessary component of electronic or computer literacy.

A Historical Overview

Unbeknownst to most people, copyright laws did not come about as a means to protect the “natural property rights” of authors. Rather, they represent a limited privilege that is granted to authors by the state for a variety of reasons. Following the invention of the printing press in the 15^th century, stiff competition between publishers established a need to protect their ability to profit from works they had purchased and printed. The easy mass-production of texts also took control of published works away from the Church and the government, allowing the dissemination of dissenting viewpoints. These developments led to the establishment of copyright laws, the purpose of which was to protect the financial interests of publishers and censor dissenting voices. England’s Statue of Anne, and the U.S. Constitution expand on these privileges, but remain grounded in the notion of copyright as “a privilege or license granted by the government for a limited period of time in order to promote not only the right of authors to profit from their labors, but also the enhancement of the public’s collective welfare.”

Major Principles of U.S. Copyright Law

The goal of U.S. copyright law is to strike a balance between the rights of an individual author and the good of the public. For this reason, the fundamental principle of “fair use” has existed throughout our history. In determining whether any particular case represents fair use, there are no black-and-white rules, rather there are a series of factors to take into consideration. Ideas themselves cannot be protected. One reason for this is that ideas are seen as universal truths that are accessible to all and cannot be owned by a single person. Also, because an individual’s ideas are dependent upon many ideas developed by others, an idea is a communal property. Copyright is only meant to protect an author’s specific expression in a fixed tangible form.

Copyrights in the Electronic Environment

Even when they are properly understood, these principles do not always yield clear answers when dealing with electronic texts. However, a broader understanding of copyright principles can still serve as a useful guide for professional communicators.

With this in mind, Howard now returns to his scenarios to see if this informed perspective sheds any light on the issues they embody.

Scenario 1

In the scenario involving the repurposing of a famous photograph, its inclusion on an annual report would likely fail the test of fair use. The document designer should seek to obtain permission and a copy of the original image from the original copyright holder.

Scenario 2

This scenario expresses a common misconception that an individual or company “owns” any software that they have purchased. What is actually purchased is a limited license to use the software in a certain way.

Scenario 3

In scenario 3, it would probably be legal for an individual to quote from an email, but the situation quickly becomes “clouded by the technology involved”. The author of the email may believe that copyright has been violated since she wasn’t able to publish her material through a more traditional means before it was copied, diminishing its value. However, the very act of sending this email to a discussion group would likely be considered a form of publication. Legalities aside, the most ethical course of action would likely be to procure permission from the author before quoting her.

Scenario 4

Usually, a company is the sole copyright holder of the texts produced by those in its employ. In some jurisdictions, there are laws which protect the privacy of personal communications between employees. Regardless, this scenario is less a question of copyright than it is of personal privacy.

Scenario 5

Determining whether the reorganization of data compiled in another source constitutes a copyright infringement is a tricky one, and cases have gone both ways. Howard predicts that this will become an increasingly prevalent issue with the advancement of computerized database systems in which information is automatically stored, manipulated, and accessed in a wide variety of ways. The most conservative course in this scenario, Howard concludes, would be to contact the publisher of the reference materials and attempt to work out a financial arrangement before publishing any repurposed material.

Conclusion

The advancement of electronic information technologies has created many challenges to our current model of intellectual property law. “It may well be,” states Howard, “future copyright laws will need to find radical new foundations.” Today more than ever, professional communicators need a more thorough understanding of the history and philosophy behind intellectual property law.

Barker Chapter 14

2007-12-05T13:07:00.000-06:00

Designing Indexes

Manual Indexes:
The basic procedure for creating an index is:

Review the user analysis. This will refresh you memory about the main actions and activities in regards to the software and can be used as a reference when deciding on what terms are important.
Pick out terms or phrases that you want to index. Typically tables, figures; examples; definitions; acronyms; main topics; important concepts; main tasks; tool buttons; keyboard shortcuts; menu names.
Record the locations.
Alphabetize and edit the index.

Electronic Indexes

Advantages of using this method are:

Automatic alphabetizing
Automatic formatting
Ease of revision

The process resembles manual indexing but differs in a few ways.

Review the user analysis.
Mark the index entries.
Build the index.
Edit the index.

What to Index

Command and Functions. These include all of the terms that you find on menus, as well as control and Alt key functions.
Concepts. The ideas related to the subject matter of the program.
User Terms and Questions. Relating words to synonyms that a user might know, i.e. a user wants to "quit the program", your program calls it "exit".
Glossary Terms
Proper Names of Products and Companies
Tasks and Procedures

Level of Detail

A light index will have two to three items per page.
A medium index will have five to seven items per page.
A heavy index will have eight to nine items per page.

Phrasing and Format

Primary locator numbers; the page number where the main information occurs. In some indexes this page number is in bold.
Capitalize terms.
Make entries sound like sentences.
Special terms.

History, Rhetoric, and Humanism

2007-12-03T22:06:00.000-06:00

In his article “History, Rhetoric, and Humanism,” Russell Rutter looks at a more comprehensive way to define technical communication. He begins his piece by discussing that technical writing is more than just writing proficiency; it also involves problem solving skills and the ability to work with other people (21). Technical communication, Rutter feels, needs to associate itself more with rhetoric and humane learning. Also, technical communicators need to go beyond just being users of systems; they need to be educated human beings.

Being and Knowing Before Doing and Writing: Technical Communication and the Liberal Arts Tradition
The tradition of technical communication asserts the primacy of knowing and being over willing and doing (22). According to this tradition, the person thinking is more important than the tools or systems being used. Rutter goes on to provide research of this tradition, which emphasizes the classical period, the Renaissance, and the nineteenth century. After these three periods, even more perspectives of technical communication were formed.

Scientific Progress Through Crisis and Its Implications for Technical Communication
Science and technology are often viewed as rigid subjects, and therefore most think that when writing about them, the language should also be rigid. However, this is not the case, and this thought needs to be brought into the open. The importance of the scientific method is often exaggerated, and the scientific and technological progress through spasmodic change, serendipitous discovery, and imaginative flexibility are often forgotten (26). Rigid procedures have not always brought about scientific advancement so it is hard to see how they would ensure the advancement of technical communication. Therefore, as technical communicators, if we must mimic science, we should also mimic the imaginative side as well.

The Evolution of Science and Technology and the Reductionism of Technical Communication Theory
As late as the seventeenth century, what passed as science was based on the authority of the ancients rather than experimentation (26). Technology wasn’t even really considered because it rested in the hands of guilds, artisans, and the illiterate. Rutter then goes on to describe more about the history of scientific advancement. Most of the great scientific advancements of the time came from just a few scientists. He notes that professors at Oxford were laid off because they couldn’t fill their science courses. It wasn’t until the Technical Instruction Act of 1881 that it became possible for Britons to study technical education (27). In the United States, the Morrill Act of 1862 brought about technical education by endowing what we now know as land grant colleges (27). With the increased enrollment in technology and science came a need for courses designed to teach about how to write about technology and science. However, these emphasized that the scientists provided the content, and the actual writing was just “frosting” (28). This form of rhetoric emphasized technical writing as a means to fitting facts into content outlines developed long ago. Rutter notes that by providing this history, we should be equipped with the knowledge needed to shape current practice (28).

Technical Communicators as Rhetoricians
“To understand the dynamic nature of science and technology and to discover that the supposed gods of objectivity and pragmatism are just the illegitimate offspring of expediency and misunderstanding is to realize that technical communication is rhetorical above all else (28). Rutter notes that if technical communicators aim to create versions of reality instead of serving as windows to reality, then technical communication must be fundamentally rhetorical. This is valuable in the workplace because communication should be seen as an open system, which is often not. Technical communication has to be rhetorical because its task is not to serve technology abstractly conceived but rather to produce “writing that accommodates technology to the user” (29). “Technical communicators, because they depend on both ‘knowledge and practice,’ because they rely on learning as guide to experience, and because they need to bring eloquence, empathy, and imagination to the world of work are—and should be expected to be—rhetoricians” (29).

The Values and Limitations of Research on the Culture of the Workplace
Rutter writes that the research for redefining technical communication defines a problem that it cannot be expected to solve. Through his reaserach, Rutter has found that technical communicators must do more than write. They must also possess the ability to function productively in the collaborative context of the workplace (30). Writers must be able to focus on the culture as an entity in which they must fit themselves. However, Rutter finds this similar to fitting content into pre-existent content outlines, which will not produce a result of progress (30).

Conclusion
Rutter concludes by stating that he wants to avoid negativism, and that he is not trying to deprecate the efforts of those who have devoted productive lives to writing well and teaching others to write well (31). However, he writes that the best way to advance would be to eliminate the biases against such subjects as rhetoric, literary criticism, and the history of science and technology, and to include teaching training. He notes that if as much effort is put into this as has been for cooperative education, then we will surely succeed in broadening the base of technical communication.

Understanding the Writing Context in Organizations

2007-12-03T17:12:00.000-06:00

Linda Driskill

Linda Driskill discusses the importance of communication in written documents, she explains different situations and how communication was handled.

The Importance of the Writing Context

Driskill first talks about a marketing team and the concept they created for their direct mail piece for the National Association of Securities Dealers (NASD). The direct mail piece was catchy and to the point, however, as procedure they had their lawyer overlook the document and it failed to be approved because of legalities with the wording. She explains how the writers on the marketing did their job, but were not equipped with the legal expertise to successfully create a direct mail piece.

Why Current Models Neglect Context

The next section Driskill discusses in the problem with courses on communication. She states that the courses focus on the means for expressing meaning, no the meanings themselves (p.57).

One of the approaches to organizational communication is structural-functionalism which requires the focus to be on the mechanisms of the organization. This theory which is influenced by the Shannon-Weaver Theory is based on reducing noise in the system and creating a flow rate to channel information. Shannon-Weaver Theory was not concerned with people or why they needed to communicate. Schramm revised the Shannon-Weaver model it was more focused on the environment were communication took place and recognized that people were involved and that feedback is part of communication.

External Sources of Meaning: Mutual Funds Industry Example

Driskill explains external sources of meaning to be influences on the writers they are not absolute some examples of external sources of meaning are money supply and credit availability. Basically the factors that directly affect the business at hand but are not factored into the work are external sources of meaning.

Internal Sources of Meaning: The Challenger Accident Example

The structure, size, and technology of the organization will affect the role people play and the way rhetorical situations are defined (p. 63). Some of the factors of internal sources of meaning are: corporate culture, individuals, and situations. Internal factors deal greatly with people and their perceptions at work and how they communicate and how people receive the communication.

Organizational Situations and Rhetorical Situations

This addresses knowing your audience and knowing that not one particular type of audience is reading your information. Driskill refers back to the example of the marketing team for NASD. Knowing that not such a simple audience will be reading you document, a person who looks deeper into the meaning might be upset with the word choices and deem them unfair or illegal.

Implications for Teaching

Driskill talks about identifying the different situations that occur and how information and communication was handled is the best way to learn for the future and to correct any communication flaws. It is important to recognize the internal and external sources of meaning with teaching communication models.

Barker - Chapter 13 - Using Graphics Effectively

2007-11-28T17:07:00.000-06:00

Writing Software Documentation: A Task-Oriented Approach

Thomas T. Barker

Chapter 13 – Using Graphics Effectively

In this chapter, Barker explores on the use of illustrations in manuals and online help. He offers examines the role that images play in informing users, and presents guidelines for their effective use. This chapter also discusses the different types of graphical elements available and how they function.

Barker begins by presenting an example from a printed document and an online help screen that make use different types of graphics to deliver information.

Guidelines

Barker presents 4 guidelines for using graphics effectively.

1. Identify Needs for Graphics by Your Users

Barker asserts that graphics should serve to support two user questions: “How can I use the program easily?” and “How can I put the program to work?” That is to say, the graphics should help the user locate and act in order to efficiently operate the program, and they should also help the user understand, providing education, guidance, and support for workplace tasks. Graphics are not to be used as decoration, but as a way to explain concepts and illustrate examples. Revisit your user analysis, and think of ways in which graphics can help in meeting user needs.

Where Is It?

Graphics can serve to help users locate information in a number of ways. This includes:

Show the user where to look to perform tasks
Show concrete versions of abstract things
Make visuals clear

What Is It?

Graphics can be used in various ways to help define concepts unfamiliar to the user. Users often require subject-matter knowledge or background information about a program or idea. Graphics can help provide this understanding through examples and metaphors.

Examples can show things like documents, reports, or printouts. This could also include showing sample data, all of which helps users identify the various aspects of a procedure. These often benefit from labels and explanatory text.

Metaphors involve illustrating an abstract concept by relating it to something the user already knows. Metaphors can help users to quickly grasp an idea without having to learn it from scratch. A prime example of this is the desktop metaphor used by many operating systems.

How Do I Do It?

Graphics can also be used to effectively demonstrate and support sequential actions. Graphics answer the question of “how?” by giving a visual overview of step-by-step procedures. A flowchart is a good example of this type of graphic. These help users to form a mental model of a process that they need to perform.

What’s the Big Picture?

Graphics can also be used to give users a broader understanding of a concept or process. Barker lists four forms that these illustrations may take:

Overall Program Diagrams
Menu Maps
Conceptual Overviews
How to Use the Manual

2. Set Graphics Styles

Just as you set styles for text, you should also use consistent styles when incorporating graphics into your document sets. Some of these stylistic elements include boxes and frames. These styles should be established early in the project, communicated to team members, and recorded in the documentation plan.

Barker lists several style elements that are of particular importance for graphics:

Lines
Fonts
Arrow Styles
Box Styles
Frame Styles

In designing graphics, it’s also important to consider the degree of realism that you will utilize. All of these styles should be carefully documented in a table.

3. Revise and Edit

Once you have established standards, you should revise your illustrations based on those standards, in addition to overall correctness and consistency. Barker presents several points to keep in mind when revising graphics. “Graphics,” he states, “present the user with the thing itself rather than the word for the thing.” For this reason, graphics must be designed with a clear purpose. At the same time, it is important to recognize the value that words have in helping users to internalize a concept or process. This means that it is important to strike a balance between words and graphics when designing documents. Barker lists and discusses various aspects of documents that can incorporate or be augmented by graphics. These include:

Titles
Labels
Placement
Rules and Lines
Size
Colors

4. Revise for Typography

Typography refers to the arrangement of images based on a logical structure. Guidelines that can assist in achieving this are as follows:

Make important things larger
Make important things darker
Make important things central
Make important things sharper
Align related things
Put first things left, later things right

Discussion

“If a documenter has done the job well,” states Barker, “the user will not just press the correct key or button but do so in the context of meaningful work.” Graphics can help users to make clear connections between software operations and workplace actions by describing operations in meaningful ways.

Showing How Tools Apply to the Workplace

Illustrating the use of tools is directly related to the concept of task orientation. In some ways, it is the simplest form of instruction. You can support operation of interface elements (the “tools” of the program) by using images of the actions taking place, or illustrated tables of commands.

Show Results of Software Operations

Showing results occurs on all three levels of task orientation—teaching, guidance, and reference. An illustration of a tool combined with an illustration of the result of it’s use, work together to support the operation/result model of instruction.

Keys to Usability

Additional ways that illustrations can be used to support task oriented usability include:

Presenting overviews to integrate software with workplace activities
Suggesting functions and uses
Making abstract concepts concrete through metaphors

Barker concludes with a glossary and checklist for incorporating and evaluating the use of graphics in a project.

Selfe & Selfe - The Politics of the Interface

2007-11-28T12:08:00.001-06:00

The Politics of the Interface

Cynthia L. Selfe and Richard J. Selfe, Jr.

Introduction

The authors begin their article by recounting a story that was told to them by a colleague. Upon returning from a trip to Mexico, an Indian-born resident alien professor was detained at the border and eventually fined, since he did not have the required documentation to enter the country. The authors view this incident as an example of imperialism and unjustness, and use it as an analogy for the politics of computer interfaces. “It is at the geopolitical borders of countries,” state the authors, “that the formations of social power, normally hidden, are laid embarrassingly bare—where power in its rawest form is exercised.” They go on to state that teachers who use computers to teach English often contribute to the establishment and maintenance of these sorts of borders in their own classrooms, characterizing this activity as “the systematic domination and marginalization of…women, non-whites, and individuals who speak languages other than English.” In their article, the authors hope to describe the political and ideological boundaries associated with computer interfaces, ways in which these boundaries are constructed along ideological axes, how borders in computer interfaces can be mapped as complex political landscapes, ways in which borders can prevent the circulation of individuals for political purposes, ways in which students and teachers can learn to see and alter these borders in productive ways, and tactics that teachers can use to enact a radical pedagogy of electronic borders.

Computers as Learning Environments: History and Motivation

In this section, the authors begin by discussing the increase of computer technology within the field of English composition instruction. Computer-supported learning environments have generally been viewed optimistically by teachers, as “places within which teachers and students can try to enact educational practices that are more democratic and less systematically oppressive.” The authors quote research, however, that demonstrates that minority students and those of lower socioeconomic status remain a “technological underclass”, and are the least likely to gain computer skills during their public schooling. In order to face this reality, instructors are encouraged to become both technology users and technology critics, reflecting on the cultural and ideological characteristics of their technology.

Mapping the Interface of Computers as Educational Space

The authors acknowledge the ambitiousness of such a project, and declare that they will focus specifically on computer interfaces. They go on to describe interfaces as “cultural maps” of computer systems, maps that have ideological underpinnings. Like all maps, they reflect the historical and social values of the culture that produced them. “Primary computer interfaces,” they state, “do not…provide direct evidence of different cultures and races that make up the American social complex, nor do they show much evidence of different linguistic groups or groups of differing economic status.” Instead, the authors argue that these interfaces tend to exhibit the “monoculturalism, capitalism, and phallologic thinking” of “male, white, middle-class, professional cultures associated with the military-industrial complex.”

Interfaces as Maps of Capitalism and Class Privilege

The authors present examples of how these maps are exclusive, in that they based on a world that middle- and upper-class users know and are comfortable within. This includes using analogies such as the desktop, folders, files, documents, telephones, fax machines, clocks, watches, and calendars. They suggest that alternative icons could be used to represent different worlds, such as a kitchen countertop, a mechanic’s workbench, or a fast-food restaurant. They describe the white pointer hand in the Macintosh interface as a semiotic message about race. They also identify clipart collections as including images that are predominantly white, professional, and office-oriented. The authors also an association between computer use and capitalism, as more and more people are subscribing to internet service providers in order to access online information.

Interfaces as Maps of Discursive Privilege

Primary interfaces, the authors assert, tend to reproduce the privileged position of standard English as the default language of choice. Computer users must often pay extra to purchase versions of software that have been produced in other languages. Using English versions of software forces students from other races and cultures to “submit to the colonial power of language and adopt English.” The authors go on to describe the fundamental level at which many computer systems are based on English, so that even non-English speakers much make use of English symbols, such as those contained in the American Standard Code for Information Interchange (ASCII) character library.

Interfaces as Maps of Rationalism and Logocentric Privilege

In addition to the previously mentioned interface associations, the authors also believe these interfaces to be aligned with “values of rationality, hierarchy, and logocentrism characteristic of Western patriarchal cultures.” These values inform how information is represented and limit alternative possibilities. The article goes on to describe ways in which this hierarchical framework is actually limiting computer development. By incorporating methods of data representation such as “bricolage”, which refers to the construction of meaning through the arrangement and rearrangement of concrete materials in an intuitive rather than logical manner, the authors look forward to interfaces that exhibit the “epistemological pluralism” proposed by Turkle and Papert. Taken together, these interfaces “do violence to” minorities, imposing “a master narrative that resonates…with modern myths of technological progress.”

What to Do?

To respond to this phenomenon, the authors recommend that educators begin by locating themselves in relation to the map. Are we the cartographers creating the map, or the members of a dominant group that profits from it? We can then attempt to view the map from other vantage points to get a broader perspective. In this way, educators are better equipped to teach students how to view the interface “as an interested and partial map of our culture and as a linguistic contact zone that reveals power differentials.” Educators can also work with students and computer specialists to reimagine and redesign interfaces such that they avoid “disabling and devaluing” minorities. The article presents several tactics for accomplishing this.

Becoming Technology Critics as Well as Users

One tactic proposed for addressing this issue involves working to encourage a general level of critical awareness about technology issues among current teachers, and those planning to teach. As technological literacy and training is promoted within academia, it is important to also teach technological criticism, so that instructors think carefully about the implications of using technology in their classrooms.

Contributing to Technology Design

Humanist scholars and teachers should be involved in the practice of interface design. In some cases, this involvement can occur directly. However, since most instructors will not be directly involved in designing computer interfaces, they can influence the process by promoting collective professional action aimed at general technology design efforts. Online discussion forums can also be utilized in promoting this aim.

Reconceiving the Map of the Interface

Another strategy would be to involve composition teachers and students in a project to revise interfaces as texts. These projects can involve reconceiving interfaces according to a broad range of perspectives. New ideas for interfaces based on a range of “cultural, linguistic, and ideological perspectives” can be designed and expressed through either prose descriptions, drawings, or computer illustrations. This process could also include assembling libraries of icons and images that represent a diverse range of cultural values.

Toward a Critical Reading of Interfaces

The goal of eliminating oppression in our society represents a broad, ongoing challenge involving every aspect of life. For this reason, English teachers must work to bring these issues to light as they relate to computer interfaces. The article concludes with a quote from Winograd and Flores, who state that, having identified the ideological boundaries inherent in computer interfaces, we have a responsibility to “work towards unconcealment…and let our awareness guide our actions in creating and applying technology”.

Barker - Chapter 11 - Laying Out Pages and Screens

2007-11-28T09:44:00.000-06:00

Writing Software Documentation: A Task-Oriented Approach

Thomas T. Barker

Chapter 11 – Laying Out Pages and Screens

This chapter describes two main elements of document design: the design of the screens and pages and the design of type. Barker begins by presenting several graphics illustrating major trends in page and screen design.

Guidelines

Barker’s 6 Guidelines for designing pages and screens proceed as follows:

1. Review the User Analysis

The goals of layout resemble those of document design in general. First, it’s designed to meet dynamic needs with a static document. Second, it should support overall task orientation. And third, it should accommodate the visual needs of the user, the need to learn and do through images rather than words.

2. Create Page Grids

Page grids define communication spaces by drawing invisible “fences” around areas of a page. They act like a scaffold or framework onto which text and graphics can be anchored.

These can incorporate design elements such as:

Grid lines
Margins
Columns
Gutters
White space
Baseline

3. Define the Page Grid Using Styles

The page grid defined in the last step should provide a road map for almost all your pages. At this point, you should define the styles that you want to use to set up the pages. This includes page elements such as margins, gutters, line spacing, the size and font of text, and so forth. Special concerns when designing for the screen include elements such as column spacing, arrangement of headings, and how hyperlinks are indicated.

4. Draw Thumbnail Sketches

A thumbnail sketch uses lines and spaces to show how pages should be organized. One method for producing these involves folding a piece of paper in half multiple times to produce a grid. At this point, you may draw in margins, columns, and page features. It helps to model your page design on a design you have seen that seems particularly suited to your project.

5. Set up Pages and Styles in Your Word Processor

Using a word processor or desktop publishing program, you can establish specifications for pages by defining both styles for text and page setup parameters. There are two very important reasons for using styles. These include:

The styles can be changed later at a global level
The styles ensure consistency across a document set

6. Determine the Layout of Help Documents

Screens offer an array of features you can use to create a usable and intuitive design. These include frames, narration strategies, hypertext links, and image maps. Remember that users search for information differently on a screen than on a page. It is important to understand the constraints of page and screen design, and how they differ. Barker presents a table listing some of the differences between page and screen layout elements.

Discussion

Designing Communication Spaces

There are two important aspects to any document that need to be decided:

The degree of modularity pages and screens need
The degree of structure pages and screens need

Modularity means breaking the information into chunks of text and graphic units to make them easier for the user to digest. Ask yourself if your page design contains all of the information needed by users to perform and fully understand the task. Barker quotes Edmond Weiss’ assertions that modules should be functional, independent, and small, providing greater ease of access that unlocks information. Online help documents can segment information more easily through the use of pop-up windows, expandable text, and rollovers.

Structure refers to the arrangement of information according to patterns. This requires defining spatial relationships between chunks of information. Research into how people process information has shown that individuals locate information in documents by remembering the physical location of information on the page. Elements that contribute to structure in a document include:

Rules
White space
Bullets
Chunks

Common Page Designs

In this section, Barker lists some common page designs. These include:

Two-Column Format: Allows the user to easily distinguish between guidance information and support information, and works best with procedures and step-by-step instruction. It is not as dense as a one-column format.

One-Column Format: This format keeps task information together in a linear form, and can be a good way to present long sections of prose.

The Elements of Page Design

In this section, Barker lists and discusses various elements that the document designer must consider in order to produce an effective document.

The Left Margin
Columns
Headers and Footers
Icons and Diagrams
Screen Shots
Rules
Pagination

Barker concludes with examples of common page and screen designs, a glossary, and a document layout checklist.

Barker Chapter 12 - Getting the Language Right

2007-11-19T23:32:00.000-06:00

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

2007-11-18T13:43:00.000-06:00

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:

Visual simplicity
Ease of use
Clear operating instructions
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

2007-11-12T23:48:00.000-06:00

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?

2007-11-12T19:18:00.000-06:00

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:

Had specific rhetorical modes and formats which were pitched to specific readers (format).
Had a specialized vocabulary and an objective style (style).
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:

The world is out there.
Properly applying our minds, we can know it.
There is a best way of knowing the world.
The best way of knowing the world is available to any intelligence.
It is independent of language and human quirks.
Language is a way of using and telling this access.
We are able to determine the correct and incorrect uses of language.
So distinguishing is difficult we often fail at it.
If we can purify language and our consciousness, we can formulate a perfectly correct language, a universal language, which we would not make mistakes.
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

2007-11-12T17:09:00.000-06:00

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

2007-11-05T23:43:00.000-06:00

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.

Involve
Explain
Listen
Enforce
Reinforce
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

2007-11-05T21:06:00.000-06:00

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.

Barker Chapter 10

2007-11-04T16:09:00.000-06:00

Designing for Task Orientation

In this chapter Barker discusses the importance of designing a manual and what to look for and what to include and where. He starts the chapter by talking about the table of contents. The table of contents creates an outline for the manual and should be easy to use, he states the following guidelines for creating a table of contents:

1. Create the table of contents
2. Match the user analysis with information design strategies
3. acknowledge production constraints in document design
4. test and review the design
5. follow a design process for online help

The next important topic Barker discusses is matching the user with the manual. What he means by this is knowing what the purpose for the manual is. He explains it as designing for different groups and to consider the following the elements:

Navigational aids: make sure the user groups get to the information pertinent to their needs.
Scenarios: give each group a role model, examples of usage help users identify themselves and their main workplace activities.
Icons: identify information for each group. They are eye catching and direct them to shortcuts.
Metaphors: make implicit relationships to the workplace explicit so users can see and feel like the document is familiar to them.

He also talks about designing for specific program issues, this helps the user meet the difficulties identified, Barker says to design your documentation to include:

Job performance aids: cover technically difficult or repetitive tasks. Usually stand alone documents.
Background information: this helps the users feel like you’re making sure they don’t fly blind.
Special forms: tear-out forms or printable documents can help users collect information in the field for later inclusion into the document.

It is also important to meet the user’s tasks needs, the following helps the user to do things:

Illustrations: show photographs, drawing, or clip art of users performing familiar tasks.
Layout design: make the document fit the user’s desktop.
Examples of usage: Include introductions explaining examples of use of the program.
Special document sections: Provide a “getting started” section with three or four useful examples.
Tips: include performance-oriented elaborations and introductions.

Meet the user’s information needs:

Explanations: explain why file naming and directory structuring of program files can help retrieve reports and files.
Examples: show program data imported into a word processing or database program.
Meet efficiency goals/command summaries for efficiency. provide shortcuts, quick-key combinations.
Problem Solving: encourage problem solving by suggesting options, encouraging creative solutions and thought-provoking problems.
Emphasis on information management and communication work: identify functions that relate to information management and communication.

Barker states the importance and knowing the user’s need and learning preferences and to recognize the user’s usage patterns. After deciding the features you would like to use
it is then important to realize the features you can afford and decide according. After the features are decided it is important to test and review the document.

Barker then discusses online help documents, he stresses the significance of naming the topics appropriately. With that he talks about interconnected elements. This means selecting topics that refer to another topic.

Barker finishes the chapter talking about the overall document. He states that within each manual there will be two or three manuals in one for the different levels of the user. He also talks about making the manual user friendly, what he means by this is to help the user navigate. He gives an example of placing the index in the front matter which is usually not done, the users rejected the manual because it didn’t meet their expectations. If you choose to switch things up, explain it to the user. He talks about the importance of headers and footers and layering on a page, which means having two forms of information on the page at once to satisfy more than one reader.

Barker Chapter 9 - Editing and Fine Tuning

2007-10-29T14:22:00.000-05:00

In this chapter, Barker discusses the steps for editing and fine-tuning software documentation. He writes that these guidelines help develop good editing attitudes and adapt the types of editing to the needs of a project. Also, they offer practical tips, rather than a specific sequence.

Establish Project Guidelines
The first guideline Barker discusses is establishing project guidelines. Each project is going to differ from all others, so you should make sure you and your writers and other editors understand the roles and the goals of the editing process. Barker notes that depending on your organization, you may find yourself in one of the following situations: writer and editor’s roles combined, writer submitting to an editor, or editor of the work of another writer. Once you have an idea of your editing role, you can identify the objectives of your project. Barker provides some examples of editing goals, including: consistency in how the user perceives or experiences the document, consistency in the purposes of the information in the documents, applicability to multi cultural or cross cultural readers, correspondence of tasks and activities in a manual or help system, and smooth interaction among editors and writers.

Understand the Types of Editing
The next guideline Barker discusses is understanding the types of editing. He writes that there are four types of edits that roughly correspond to the stages in the writing process. These four types are managerial, substantive, copy editing, and proofreading.

Barker writes that managerial editing concerns itself with the documents and their planning and production rather than their actual format and content. This type of edit requires involvement during the entire documentation process because you are tracking and coordinating all the production processes, and the relationships with the other documents. In the managerial editing process, the document and design plans are looked at for consistency and accuracy. This is also where the style is set for the entire project.

Substantive editing involves editing language and information. In this kind of editing, you work very closely with the author to address the overall organization and structure of a document. Barker writes that the following are things you look for in a substantive edit: overall organization of the document, fluency of one sentence to another, parallelism in steps and lists, proper use of description, clarifying definitions, elements in right order, divisions of information are logical and consistent, maintaining correct emphasis on certain elements, minimizing redundancy and repetition, omitting irrelevant or inappropriate material, and finding instances of missing information.

Next, Barker writes that copy editing concerns itself with editing for grammar, mechanical style, and format. In this type of editing, you pay attention to all the surface-level elements of the words, sentences, paragraphs, pages and books. Barker also notes that copy editing is done on documents that writers have already tested and subjected to user and other reviews, and that this kind of edit doesn’t necessarily assume that you know a great deal about the reader of a specific document. The following are some of the things you look for when copy editing: spelling, subject/verb agreement, sentence fragments, incomprehensible statements, suitability of screen shots, typography, correct style, header and footers, margins, spacing rules, mechanics and punctuation, word compounding, form and use of acronyms and abbreviations, and cuing patterns.

Proofreading is the last stage you go through before printing the production copies of a document. In this form of editing, you look at the elements of a document, and it entails making sure that all the changes suggested during the copy edit were done. Barker notes that since this is a tedious process, it is often done with a partner. The following are some of the tasks you perform when proofreading: checking for consistency in the table of contents, checking lists of tables and figures, checking that navigation and routing sequences specify the correct location of the necessary information, cross-referencing the tutorial lessons, checking that screen shots and figure numbers are unique and consecutive, checking that numbered or letter sequences are correctly labeled, and checking that spine copy, bleed tabs, and index pages are consistent.

Plan Your Editing Tasks
Barker writes that planning for editing should begin at the beginning stages of a project, but that often, editors get brought in later as a last-minute quality control measure. If this happens, you will have to do some retro planning to accomplish the editing tasks. Scheduling depends on the kinds of editing work you will be doing on a project. Depending on how many writers and your editing role, you will have to schedule two things: time for going over documents as an editor, and meetings with authors and developers about your work.

Barker continues his discussion of planning your editing tasks by stating that scheduling editing work allows you to budget in the time you need to complete your editing task and match your activities with others on the documentation team. The time it takes to complete an editing tasks depends on a number of things, including: the quality of the work you receive for editing, and the nature of the material you’re editing. Barker goes on to discuss how to plan for each of the four types of editing.

For managerial, you should plan to attend meetings and edit documents such as the documentation plan, test and review forms, the style guide, and all the documents associated with the project. Communication is the key for this plan and editors need to plan for the following events: establishing styles for print and online documents, a meeting to review the documentation plan, occasional memos to communicate updates to the documentation plan, reminders of deadlines, drafts, reviews, and test activities, periodical updates to the project style guide.

For substantive editing tasks, you should check documents as they are being developed and advise the writer on how to organize and design the content of a document according to the reader’s needs. Barker writes that these editors need to schedule the following events: review the documentation plan and style guide for the project, deadlines for outlines and rough drafts, deadlines for returning outlines and rough drafts, meetings to discuss editing comments and suggestions.

Next Barker discusses what is needed to plan for copyediting. He writes that this type of editing typically only requires on session per draft and is done after all the document is completely written in draft form. Copyediting usually takes longer than substantive editing because you may have to make passes at a document looking for one feature after another. The following are events copyeditors need to schedules: start and end dates for editing sessions on drafts, and meetings with writers and drafters.

The last type of editing to plan for is proofreading. Because of its tedious nature, it is wise to schedule two people for this task. Working as a pair helps to avoid mistakes and letting errors slip. Proofreaders need to schedule the following events: arrange proofreading sessions with another editor, and scan documents for grammar, spelling, headings, graphics, figures, tables, layout, notes, table of contents and index.

Barker notes that you should confuse editing tasks with other tasks, and the following tasks should not be confused with editing: don’t supply missing material, don’t supply missing screen captures, don’t write more than short passages, and don’t edit a manuscript more than once.

Develop the Appropriate Editing Forms
Barker writes that because editing requires you to establish relationships with other persons on the documentation team, you will find that creating editing forms, or using existing forms, can help you regularize your procedures and communicate with others more clearly. During document planning, you should have planned what styles the project was going to follow during writing. You should consult your documentation forms when editing to update the project plan, and to identify styles it specifies and reuse as much of the original information as possible. Barker notes that one of the most important forms you can create is the style sheet, which is a way of recording information about your editing convention as you go along. Style sheets are not a substitute for a style guide, which specifies styles for a document ahead of time. Barker emphasizes the importance of a style guide by discussing the purposes it fulfills: regularizing the production of documents, and setting standards that the members of a documentation team can follow. To develop a style guide, you should first look at existing style guides and then consider constructing a style guide for a specific project.

Conduct Editing Sessions
The final guideline Barker discusses is conducting editing sessions. The number one requirement of an editing session is to have no distractions. It is also a good idea to have a checklist handy while you’re editing. To ensure productive editing, Barker suggests two techniques: editing with a partner, and shortening editing sessions.

Discussion
Barker then goes to write about editing graphics and how each of the types of editing relate to this type of editing. He also discusses writing versus editing, stating that when you edit, you should try to see your editing tasks as separate from your writing tasks. This discussion also includes editing for cross-cultural readers by using either a globalized or localized language, and editing for translation, which means writing that is easily rendered into another language.

Campbell concludes this section and the chapter by discussing knowing what is correct, taking a constructive attitude and consulting standard style guides. To know what is correct in your documentation, you should look to guides, users and the documentation plan. Finally, Barker notes that seeing yourself, as a partner instead of an adversary will help your attitude.

Campbell Chapter 9

2007-10-23T15:34:00.001-05:00

No One Ever Told Me About That

You have three choices for notifying users about a policy or procedure.

Announce in person
Communicate it in writing
Send it be e-mail

Which one you choose will be based on part preference and part circumstance.

Factors that determine how you notify your users depend on:

Amount of material
Nature of the material
Complexity of the subject
Organization's standards
Communication method
Size of user group
Urgency
Location of users

Notifying in writing

Pros to notifying in writing are that it communicates the policy or procedure in a uniform way to all users. It can be distributed in mass and reaches users at all locations, on all shifts. It serves as legal documentation. And it formalizes and reinforces the message.

Cons to notifying in writing are that remote locations and later shifts may get their copies late and feel slighted. It may sound rigid or bureaucratic. It eliminates personal contact and the ability to ask questions directly of the issuer.

Tips for notifying in writing:

You're writing for an external audience such as an accrediting agency or customer
The audience is large or widely dispersed
The material is complex or lengthy
The subject is noncontroversial
Personal contact is unnecessary

Notifying in person

Doing this can take many forms: group meetings, individual meetings, phone conferences, or videoconferences.
The main advantage of notifying in person is that is gives direct contact with the issuer, which tends in increase cooperation and reduce resistance.
The main disadvantage of notifying in person is that meetings can be both hard to coordinate and unpleasant to conduct.

Tips for notifying in person:

The subject is simple or the user group small
You need to convey a sense of urgency or importance
The policy is ambiguous and needs explanation
Unofficial expectations differ from official policies
The subject is controversial or sensitive

Notifying by e-mail

E-mail is a hybrid approach to notifying allowing the user to ask questions to a written announcement. E-mail is best used when you have on-line policies and procedures or most of the organization's communication flows through an e-mail system and users are comfortable with it.

What to put in your notices

Written notices

Identify the policy and procedure
Give a summary of it
Include logistical information (title, number, effective date, implementation time frame, who's covered, whom to contact with questions or problems)
Include a brief summary of the substance (reasons for it, basic provisions, user responsibilities, and the impact it will have on users)

Verbal notices

Will the information session be introductory (brief and very general), informational (lengthier, containing more substantial information), or a training session (lasting as long as necessary covering all operational details)

Notify managers first before issuing a general notice to the company. Getting managers on board will keep their staff in line behind them.

Campbell Chapter 8 - Did I Forget Anything?

2007-10-23T12:37:00.000-05:00

I want to apologize for not posting this earlier. I guess I wasn’t paying attention yesterday, and I clicked ‘Save’ instead of ‘Publish.’ I think it’s quite fitting for the Did I Forget Anything? chapter. Oops.

Campbell begins this discussion by stating that the writer of a document is ultimately responsible for mistakes and errors. Therefore, a writer’s goal is to make both content and form as nearly perfect as possible.

To create a perfect document, it must go through a review process, which fine-tunes the document and double-checks for accuracy and spelling. Since this can’t be done at once, there are five different types of review, each dealing with a different aspect. These reviews include: verification, validation, editing, proofreading and approval. Campbell notes that these reviews can be combined, but it’s a much more demanding task and requires greater skill on the reviewer’s part. She suggests using multiple reviewers to speed the process, but the real key is to build adequate review time into the schedule up front.

Campbell then goes on to discuss verification. She notes that verification and validation are often skipped, but they shouldn’t be because they provide the foundation of the finished product and are the main concerns of both the reader and the organization. When you verify, you’re checking for accuracy. There are a number of different verification methods, which include: comparing the final draft to the original, checking it against source documents, confirming numerical and statistical data or assigning a content expert to do the review. Campbell writes that verification is especially important in procedures, where near perfection may note be good enough.

Next, Campbell discusses validation, which is checking for usability. She writes that you should read the policy completely through to see if it makes sense or if anything is missing. The best way to validate a policy is to have several people read through it and watch their reactions. Make notes of their reactions and ask them for honest feedback. Campbell also notes that validating procedures takes longer because you’re actually testing the steps and the sequence. There are numerous techniques for validating procedures, which include: walk-throughs, observation, focus groups, and surveys. Each of these methods require you to go through the basic steps of preparation, testing, debriefing, and documentation.

The next review process Campbell discusses is editing. She writes that it presents the unique challenge of improving the policy or procedure without changing the meaning. The main purpose of the review is to check for items such as format, wording, consistency, flow, cohesion, layout, and visual appeal. The number of edits you to through depends largely on the document and the project. Campbell notes that you should be careful not to confuse the function of editing with the functions of validation and verification. To edit, you must know what you want from your document. In the case of policies and procedures, it’s readability and usability. The mechanics of editing are largely a matter or organization and consistency. Campbell continues by writing that editing should be done with an eye to the important matters of mechanical correctness, because trivial ones will be caught in proofreading. When you edit, you should review the page layout, consider the design elements, and scrutinize everything for consistency and logic.

Campbell continues with the next review, which is proofreading. She writes that it is as important as the other reviews, but for a different reason, which is your audience assumes that if you let little things slip through, you’ve probably let some big things slip through too. She also writes that proofreading has a bad reputation because it is seen as boring, but it is actually a demanding, time-consuming step that requires discipline, concentration, and patience. Campbell notes that the secret to effective proofreading is decontextualizing, which means that you must reverse the learned habit of reading for meaning and concepts. There are a number of ways to proofread, which include reading backwards, reading aloud, reading into a tape recorder, reading to a partner or reading diagonally. When proofreading, you should look for every single imperfection, typographical errors, punctuation, spacing, spelling, agreement, page breaks, titles, misplaced words and phrases, alignment, names, numbers, typestyle, typesize and margins. Campbell also notes that you should be especially careful when proofing graphics, and to be aware of personal blind spots. When proofing your own work, Campbell emphasizes decontextualizing. If you are under time constraints, Campbell suggests having different people proof for different aspects simultaneously or using free-proofing.

The last review process Campbell discusses is approval. You should talk with your approvers throughout the process and not wait until the end. If you consult them periodically throughout the process, your writing won’t come as a shock to them. Your approval process should never be haphazard, casual or done at the last minute. Instead, your procedure should outline the approval cycle and time frames. It should also encourage approvers to solicit input and comments from within their own areas. Often, slow response from approvers causes a time problem. Campbell suggests using a well-designed form that’s fast and easy to fill out to help conquer these delays. According to Campbell, you shouldn’t be disturbed if your approvers don’t agree. This helps you identify differences of opinions before the policies and procedures are in force. Your job with differences of opinions is to coordinate and communicate. Campbell also writes that you should try to include unofficial approvers because they are influential people who give an unofficial thumbs-up or thumbs-down on the final product since they will use the product every day.

Campbell concludes this chapter by discussing who should perform these reviews. She emphasizes the importance of having other reviewers look at your work because they bring a fresh eye and a fresh perspective. They also bring their own marks and styles, so it is important to coordinate and communicate effectively with these reviewers. Campbell notes that at times another reviewer may not be available. In these cases, you’ll have to exercise twice your normal discipline since you’ll be the sole developer, researcher, writer and reviewer all at once.

Barker - Chapter 8 - Conducting Usability Tests

2007-10-22T00:56:00.000-05:00

Writing Software Documentation: A Task-Oriented Approach

Thomas T. Barker

Chapter 8 – Conducting Usability Tests

Barker defines the process of testing documents as “procedures for gaining empirical data about [their] usability.” This is accomplished using three basic types of tests: procedure tests for task performance, tutorial tests for skill and understanding, and reference tests for access to information. The chapter presents a 10-step test plan for conducting these tests.

Guidelines

Good testing requires careful planning. Barker suggests the following 10 steps be followed.

Step 1 – Decide When to Test

Testing often occurs after a draft of the documents has been produced, however it can take place at various stages in the project depending on your testing goals. A Predictive Test can be conducted during the design stage, a Remedial Test during writing or development, and an Evaluative Test after the document has been completed and delivered.

You must also determine what parts of your documentation you want to test. Determining this can be assisted by relying on the objectives that you set for your documentation, and the user analysis that you previously performed.

Step 2 – Select the Test Points

Test points are issues or features that can interfere with the efficient and effective application of a program to a user’s work activities. These can include problems with content and problems with document design.

Try to identify points where a mistake on either of these levels could lead to user failure. Any procedure where the cost of user confusion or failure is high in terms of time or money would be a good candidate for testing. In addition to testing these procedures, you should also test the document design strategies employed to ensure that they are effective.

Step 3 – Choose the Type of Test

There are three types of tests. Performance Tests test whether users can successfully complete a given procedure. Understandability Tests test whether users can provide evidence of what they have learned. Read-and-Locate Tests test how effectively users can locate a given topic of information in a documentation set.

Step 4 – Set Performance and Learning Objectives

Performance objectives state how long a procedure should take or the frequency of correctness one can expect from users. They can be time-related, or error-related. The goal here is to collect numbers that can be analyzed and compared.

In order to produce objective test results, it is important to avoid letting the outcome of the test be skewed by bias. Prejudices can creep in as a result of various work pressures, a proforma testing atmosphere, or becoming too enamored with the product of your labors.

Step 5 – Select Testers and Evaluators

The tester is defined as the person who administers the test. The evaluator is the person actually taking the usability test. If you do not have actual users available, you will have to compromise by selecting individuals to stand in for users.

Step 6 – Prepare the Test Materials

The written and other materials provided to testers and evaluators can be very extensive. Barker lists multiple forms of test materials, both written and hardware/software based. He also discusses the importance of pilot testing, which basically amounts to “testing the test”, to ensure that the instructions, terminology, and time expectations are appropriate.

Step 7 – Set Up the Test Environment

The test environment can range from the user’s actual workplace to a controlled laboratory. A field test produces valuable real-world insight, while a testing lab offers greater control over the process. A combination of both environments is often the most effective approach.

Step 8 – Record Information Accurately

It is important to accurately record what you see and hear throughout the test. This can be accomplished using video and audio recording technology, in conjunction with copious note taking. Making use of additional observers can help fill in any details that you miss.

Step 9 – Interpret the Data

There are a number of phenomenon that can cloud the data obtained through testing. Once these variables have been accounted for, you can make changes to your document based on what the numbers reveal. These can inspire all sorts of design decisions that require skill and commonsense decisions on the part of the author.

Step 10 – Incorporate the Feedback

The final step is an obvious one. The information gleaned from the testing process should serve to enhance the document in a positive way.

Discussion

In this section Barker offers a variety of thoughts on the usability testing of technical documentation. These include topics such as:

The three components of usability testing: tester, evaluator, and subject matter.
The importance of user testing as part of user-driven design
Comparing field tests and laboratory tests
The cost of testing and making it a corporate priority
Various field testing methods
The trade offs between testing earlier and testing later
Distinguishing between problems with the documentation and problems with the product

Barker concludes the chapter with a glossary of terms and a checklist for use when planning and executing usability tests.

Barker Chapter 7

2007-10-17T14:59:00.000-05:00

Sorry about being so late folks. That's my (Matt) fault not Valerie's.

Getting Useful Reviews

In this chapter, Barker describes the method of producing and obtaining quality reviews of any document.
Barker describes Guidelines for Managing Documents Reviews

Review the document objectives from the documentation plan
Determine the type of review needed
Establish a review schedule
Plan the reviews
Write a cover letter with questions for reviewers
Prepare feedback material for reviewers

Review the document objectives from the document plan:

Review the document plan to find what aspects of the document you would like reviewed. For instance, the document provides task-oriented examples of processed images, ask the reviewer if the examples reflect real-world tasks.

Determine the type of review needed:

User reviews: Reviews by the actual intended users of the document.
Management reviews: Reviews by managers and supervisors associated with your documentation project.
Technical reviews: Reviews by programmers and developers of the software.
Client reviews: Reviews by the people or department paying for the software and documentation.
Subject-matter expert reviews: Reviews by experts in the professional field represented in the software.

Establish a Review Schedule:

Sequential Circulation involves making one copy and passing it from person to person.
Pros:

Low cost
Less hassle
Encourages team spirit

Cons:

Spawns arguments in the margin
Early reviewers affect later reviewers
Causes political problems (who gets it first and who gets it last)
Hard to control
Takes extra time

Simultaneous Circulation involves making a copy for each reviewer.
Pros:

Fast
Good for geographically diverse reviewers
Fosters a one-on-one relationship
Easy to control
Easy, when online

Cons:

Expensive
Takes more of your time
Fosters redundant comments
Causes version mix-ups with online

Plan your reviews:

Writing up a strategy and a schedule for the review will help it to go smoothly and be more productive

Write a cover letter with questions for the reviewers:

Indicate document objectives and benefits to the reviewer
Ask for specific advice/comments
Provide the necessary background
Tell reviewers how to mark or comment
Give dates and places for return
Thank your reviewers

Prepare feedback materials for reviewers:

People like to know what they do matters, write a note telling them that you read and paid attention to the comments they made.

Campbell - Chapter 7 - What’s the Secret to Creating Good Manuals and Handbooks?

2007-10-16T02:04:00.000-05:00

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

Nancy J. Campbell

Chapter 7 – What’s the Secret to Creating Good Manuals and Handbooks?

Campbell begins by suggesting that the key to creating a good manual or handbook lies in successfully answering two questions: Can readers find what they are looking for in a fast, logical way; and will the book physically be easy to handle and hold up to daily use?

What to Put in a Manual or Handbook

Determining what to include in these documents can be difficult. There are no formulas for determining content. The type of policy or procedure being documented and the level of detail required depend on the purpose of the document and its audience. Documents fulfilling legal or regulatory requirements, documents outlining emergency procedures, or those simply offering general employment information—all require good judgment in determining the focus and scope of the content.

What Users Want

“Users,” states Campbell, “are the ultimate pragmatists.” What this boils down to in a manual or handbook, she suggests, is easy access to information, physical convenience, and usability.

How to Give It to Them

A handbook or manual should be easy to use from both a physical and information standpoint. This can be achieved through the use of mechanical elements of design and production. Design elements involve presenting logically organized content, along with a quick and easy reference system. Production elements center around ensuring that the document is an appropriate size and shape, sufficiently durable, and capable of accommodating revisions.

The Design Elements

Campbell presents seven design elements for handbooks and manuals, collectively referred to as front matter and back matter. This includes the table of contents, list of illustrations, list of forms, introduction, glossary, appendix, and index. These elements serve to speed users to the policy or procedure that they are looking for.

Table of Contents

This design element describes what is in a book, how items are grouped, and where to find them. This is best written last, since a complete overview of the content can’t known until after it has been written. The writing process may also demand changes to the flow of topics or subject groupings. The Table of Contents merits special care, as it is often the first impression that a user gets of the document.

List of Illustrations

When a List of Illustrations is included, it’s often placed directly after the Table of Contents. You can include all of the illustrations in one list, or break each type of illustration into a separate list.

List of Forms

When a handbook or manual contains numerous forms, it is helpful to catalog them in a specific list. Most readers dislike forms, and a List of Forms helps eliminate the excuse that the form could not be found.

Introduction

The introduction is an important piece of text that orients the reader to the purpose and scope of the manual. These are almost always helpful to include, but for best results they should be kept brief.

Glossary

The glossary defines special words, acronyms, abbreviations, terminology, or jargon. The definitions are usually brief, and sometimes use examples for clarity.

Appendix

Appendices are useful for ridding the text of “material that isn’t essential to understanding or compliance and distracts readers from the main point.” Placement requires careful consideration to ensure that the material in the appendices isn’t forgotten or ignored.

Index

Campbell describes indexes as “probably the most valuable ‘speed tool’ you can give your reader…there is no faster method of looking up a reference.” In addition to the standard subject or key word indexes, one can also make use of specialized indexes, categorical indexes, and multi-manual indexes. It is design these these indexes from the perspective of the reader, using terminology that they would use. Rely on your discipline and good judgment.

The Production Elements

There are six production elements to consider when producing a handbook or manual. These include, size, paper, color, binders, cover, and dividers. In deciding on these materials, consider how the manual will be used. Three main items to consider are:

How readers will use the manual.
Under what conditions they’ll use it.
How frequently they’ll use it.

Manuals that will be subjected to heavy daily use or harsh conditions will require more durable construction.

Size

There are many convention standards that can be followed, but sometimes unconventional formats, such as laminated cards on a string, could be appropriate. Just be sure to consider all of the ramifications of using unconventional sizes.

Paper

If heavy use is expected, it pays to use sturdier paper. This is especially true if the document will be used in harsh conditions, such as a production or maintenance area where various liquids and chemicals are prevalent.

Color

Campbell identifies three color issues: (1) page color, (2) section color, and (3) binder color. In terms of paper, white is generally the easiest on the eye, but colored paper can be used to highlight a specific section and aid in navigation. Using a binder that is an uncommon color can help it to stand out on a shelf.

Binders

Sturdiness can be an important factor with binders. It is also important not to try to fit too much into a single binder or it can become unwieldy. In such situations, it is often better to separate a thick manual into two smaller binders. A three-ring binder allows for revisions at a later date.

Cover

One popular option involves using a binder with a clear plastic envelope on the front, into which a cover page can be inserted. It is also very important the binder be somehow labeled on the binding, so that the title is visible when the binder is sitting on a shelf.

Dividers

If dividers are used, make sure that they are sturdy enough and securely affixed to the pages so that they are not broken off and lost.

Distribution Issues

One should approach the issue of distributing these handbooks and manuals just as carefully as the rest of the project. Begin by developing a distribution list and checking it with several others. Overlooking certain individuals or departments can cause frustration and resentment. In creating the distribution list, those who will implement and/or enforce the policies and procedures your handbook or manual contains should always receive a copy, well those individuals who only have a general interest in the information may not need to receive copies. A distribution list can also be used to track who has acknowledged receipt of the documents, or ownership of the documents themselves.

Campbell concludes with a brief chapter summary, followed by a Tools and Resources section, in which the material from the chapter is presented in a highly practical way.

The Shape of Text to Come

2007-10-15T22:56:00.000-05:00

In his article “The Shape of Text to Come,” Stephen Bernhardt speculates some of the dimensions of change in how text is structured on a page and on the screen. He discusses how good theoretical understanding and a highly developed practical art of the rhetoric and text structure of paper documents exerts a strong shaping influence over texts produced via electronic media (410). He uses a text analytical approach to identify nine dimensions of variation that help map the differences between paper and on-screen text. These nine dimensions include: Situationally Embedded, Interactive, Functionally Mapped, Navigable, Hierarchically Embedded, Spacious, Graphically Rich, and Customizable and Publishable.

Situationally Embedded Text
Bernhardt begins this section by discussing some of the situational differences between paper and screen-based text. Reading from a screen tends to cause fatigue so extended reading will continue to rely on print, while other functional types of reading will rely on screen-based text (411). He notes that paper texts can be read anywhere, but screen-based texts are more deeply embedded in the context of the situation. Screen-based reading is often associated with task-oriented reading because it integrated with some sort of action. “Readers of screen-based texts are not so much readers as doers or seekers: they read to find out how to do something or to retrieve some bit of information (411). Bernhardt notes that the shape of screen-based text is heavily influenced by the development of help systems. He also notes that having text situationally integrated also applies to other forms of screen-based reading. Students use computers to help with writing and these computers help structure interaction. The text is embedded within systems—its texture is shaped by both the machine and the instrumental purposes and social interaction to which the text is put (412). Bernhardt concludes this section by noting that books are self-contained, while screen-based texts are dependent on a larger technological and social environment, to be used under delimited circumstances (412).

Interactive Text
Bernhardt writes that the reader’s role in a text as being active. Readers construct a text in their own image, and this is typically seen as a private matter. He notes that reading of electronic text should be viewed in similar terms. “Readers of on-screen text interact physically with the text. Through the mouse, the cursor, the touch screen, or voice activation, the text becomes a dynamic object, capable of being physically manipulated and transformed” (412). Bernhardt uses an example from the Perseus Project, which helps students visualize a staged production of a Greek play. In the Perseus model, students are able to interact and manipulate the entire set of the stage and play. The designers take active, constructive reading into the arena of physical manipulation and sensory visualization (412). Screen readers are actively engaged with the screen as they enter text and this interaction is forced, unlike a print-text. Bernhardt notes that he is not suggesting screen reading is better, but he does write that the developing genre of the electronic novel should not be underestimated.

Functionally Mapped Text
“Text, whether on page or on screen, performs a function of some sort: informing, directing, questioning, or posing situations contrary to fact” (414). This functional variation is often expressed through grammatical systems of mood, and readers can often make some rhetorical determination as to what a chunk of text is doing. In many printed texts, the functional variation is mapped semantically. Shifts are noted by phrases such as “for example,” or “to consider my next point” (414). Screen-based and print text also use visual cues of layout and typography to signal functional shifts. Bernhardt notes that when language is on screen, readers must be able to distinguish the following different functions: cue interaction with the system, cue navigation, offer system messages, informative/ideational (414). The interaction between the text and action is important for efficient reading, and they must be highly planned and have carefully constructed formatting decisions. Bernhardt goes on to write that not all areas of the screen are equal, and functional mapping tends to be the richest on the borders. “On screens, the language is the richest, there is the most going on, there is the greatest range or things to do around the edges, on the perimeters. 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” (415). The functional mapping of options is becoming more consistent in programs. Simple, yet efficient cues are being used to help guide the reader. The traditional cues of paper texts are often shadowed by the ever-expanding visual cues used in electronic texts.

Modular Text
Most texts reflect some modularity of structure: a text is composed of other texts, such as a book with chapters (416). The movement of text from paper to screen encourages further modularization of text structure. With screen texts, each module of information must stand on its own because of problems with local cohesion. A writer must assume that a user can arrive at any given screen from practically anywhere. Bernhardt mentions that even though it is possible to scroll within a window, this action is time-consuming and wasteful. Also, when text is not composed of screen-size bites, readers tend to lose their places and become disoriented (416). However, modular text does have some advantages. One text base can serve multiple audiences and multiple purposes for reading (417). Novice and expert tracks can be structured out of the same set of information, and texts of various sorts can be compiled instead of written. This is especially useful for screen-based text such as online help because a single text can be written once but used many times.

Hierarchical, Layered, Embedded Text
Print text is a flat medium intended for linear reading. It can achieve a special sort of modularization through semantic cues but it doesn’t compare to computers, which are suited to nonlinear text. Hypertext programs allow texts of various sorts to be combined into large text bases, allowing readers to move freely across various sorts of information in nonlinear ways (419). Even though screens are two-dimensional, they offer the illusion of depth. Information can be present without being visible, and the desktop can be stacked with open files—multiple applications running simultaneously—each with its own text in its own screen. (419). While paper text must embed signals of hierarchy within the linear text, screen-based text can actually be hierarchically structured. “With the combination of both hierarchical subordination and lateral links from any point to any point, hypertext offers greatly expanded possibilities for new structures characterized by layering and flexibility” (419).

Navigable Text
Readers of all texts must navigate to find information. With paper-text, readers often use signposts, such as table of contents, indexes, headings and pagination. Most readers have a set of strategies used to find information in print texts. They are often frustrated when they try finding information using electronic text because these print text search strategies don’t work. Because the screen lacks the total physical presence of printed text, screen readers often have difficulty sizing up the whole (420). The challenge of designing text on screens rests in large part on overcoming the machine’s tendency toward a homogeneous surface. Many initial attempts were borrowed from paper text, but some navigation aids work best only within electronic media. Graphical browsers can offer readers a visualization of the structure of information, so that one can see at a glance the scope and nature of large collections of information (420). Also, ties, or links, or buttons work much better in screen-based text than in paper texts. Standard navigation devices are quickly emerging so that screen readers can bring learned strategies to new interfaces and new texts.

Spacious Text
Print text is constrained by physical space. The same physicality that makes books easy to use makes them impossible to use as systems grow larger (421). There is no similar physical constraint associated with electronic text. There is both spaciousness in the amount of information that can be recorded and the design of information display. Writers of paper text are always contained by length, but since space is virtually unlimited in screen texts, there is no need to run unrelated information together to save space. “The effect on prose is liberating, freeing it from the economic constraints of inscription” (422).

Graphically Rich Text
“Electronic text extends visual composition by offering a surface with more graphic potential and greatly augmented options for text/graphic display and integration” (422). Some display options are shared by paper and electronic texts, including: white space, space breaks, margins, bullets, font sizes and varieties, headings, color, and boldface and italics. However, go beyond print’s visual effects. Readers can zoom in and out, text can flash, sequences can be animated, and video, voice or musical sequences can be part of text. It is known that people learn about complicated systems best when they have organized metaphors, and electronic information allows for the exploitation of these metaphors (422). Bernhardt notes that the phosphor glow of screen text often causes fatigue and eye strain, but that that same phosphor also offers a fluid, dynamic medium, with many more options than print has for displaying information and exploiting visual intelligence (423).

Customizable, Publishable Text
The final dimension Bernhardt discusses is customizable and publishable text. Readers can’t do much to personal print text, but electronic text benefits from being more fluid, expansive and adaptable to individual users (423). Lines and notes can be added to electronic text and the user can choose to reject or accept them and print or suppress them. The display of the text itself can be customized. Readers can suppress the display of rulers, spaces, returns, etc (425). The “same” text can display itself based on the individual user’s preferences using user histories. The control over the shape of text leads inevitably toward not just customizable but publishable text. Desktop publishing technology puts the printing press into user’s hands. Historically, much of the cost of printing has been in the production stage, but with desktop publishing technology the cost is shifted the author and the audience. Print is no longer permanent because the cost and effort of updating editions is negligible (426).

The Shape of Text to Come
Bernhardt concludes by noting that as text changes, we will develop new strategies for reading and writing. He writes that we are at a point of transition, and that “the presence of screens will become increasingly common, a part of our daily lives, close at hand in a variety of situations” (426).

2007-10-14T19:47:00.000-05:00

Relocating the Value of Work
Technical Communication in a Post-Industrial Age

Johndan Johnson-Ellias

Ellias starts off the article discussing what the primary use for technical communicators was fifty years ago. He states that after the wave of industrial technology, which includes products such as; washers, automobiles, and televisions. That information also became a valuable product. His problem with technical communication is that after the wave of industrial technology, information was second to the product. Making technical communicators subordinate. Ellias stresses the need for technical communicators to over come the subordinate role of supplying information and how to steps to industrial products and software. He wants technical communicators to apply contextualized information, helping the user understand the task at hand and the reasoning for the task.
He also states that there are three services of work and technical communicators need to be in the last category of symbolic-analytical work but they have to transition themselves there. He states the three categories being: routine production, which involves repetitive work. According to Ellias technical communication falls into this category because of routine manual writing, which produces technical procedures and follows a predetermined template. The second category is in-person service work; this includes your customer service representatives. Technical communication also falls into this category because people no longer read their instructions; they call the help line instead. Technical communicators help to set up the help line by creating stock answers to typically asked questions. The third category is symbolic-analytic work; this is the category Ellias states that technical communication fall into. Symbolic-analytic work possesses the ability to identify, rearrange, circulate, abstract, and broker information (page 182). This refers back to his idea of contextualizing the information. Ellias wants to relocate the need for technical communication, he wants the technical communicator to understand why the task is being done and for exactly what audience. He stresses the importance of not just relaying information on how to accomplish the task. He wants technical communicators to understand the task and teach the task emphasizing communication instead of technology.
Later in the article Ellias breaks the idea of communication focus instead of technology focus into four categories; experimentation, collaboration, abstraction, and system thinking. He says that that technical communicators should experiment and implement usability to discover what works well and what doesn’t. Collaboration includes working together that in technical communication it will almost always be a team project including, designers, developers, marketers and writers. When he talks about abstraction he talks about thinking about the original project and rethinking to make it more efficient. System thinking refers to thinking beyond system problems and solutions, but thinking more about how the problem occurred. He stresses those four ideas, because he feels if they are implemented in a learning environment technical communication may be able to strive to be symbolic-analytic work.

Campbell chapter 6

2007-10-10T08:29:00.001-05:00

Campbell Chapter 6

How Do I Get Them to Read This?

Campbell discusses the importance of not just creating a sound document but getting people to read your document. The first point she brings up is credibility. People need to believe your advice is going to help them and be accurate. Next she discusses hooking them, not only is it important to have credibility but she brings up the statistic that 70% of what you know about people is based on their appearance (page 206). Readers need to be able to easily tell if the document is clear, easy to read, and concise. Readers want to instantly know if this is going to be worth their time or could they figure it out on their own faster. This brings up the importance of visual appeal. Readers will think that a document is easier if it looks easy to read and clear. Campbell says that there are twenty different design elements: sentence length, paragraph length, line spacing, typestyle, typeface, emphasis, paragraph spacing, justification, indentation, margins, headings, graphics, visual weight, contrast, color, symbols, columns, lists, forms, and white space. She brings up the importance of avoiding visual clutter, which she compared to an attic or garage that no one wants to look at so they shut the door.

Campbell tells the reader that the human brain can only retain seven different items at once but can only clearly distinguish between three of the seven items. That is way the rule of three was created. The rule of three is based on not using more than three different design elements in one document.

Eye movement is an important concept to understand. Campbell talks about the limits that the eye has:

Takes in approximately forty characters at once.
Takes in three or more words per second.
Reads two or more words at one time.
Moves from top to bottom and left to right, in a zigzag or Z pattern.

That is why short sentences and paragraphs are extremely important in your document. This is also why Campbell recommends chunking your information. Campbell defines chunking as breaking the printed matter down into chunks the reader can deal with easily. Another technique used to help the reader is white space. White space simply refers to the white or non-printed area of your document. It does not however have to be white it is whatever your paper color is. The last point Campbell discusses is being consistent. Being consist in your language, your design, and your overall appearance. She talks about the reader finding his or her rhythm this helps the reader continue reading and understanding.

2007-10-09T15:52:00.000-05:00

Campbell Chapter 6
How Do I Get Them to Read This?

Campbell discusses the importance of not just creating a sound document but getting people to read your document. The first point she brings up is credibility if people are going to believe your advice is going to help and them and be accurate. Next she discusses hooking them not only is it important to have credibility but she brings up the statistic that 70% of what you know about people is based on their appearance (page 206). Readers need to be able to easily tell if the document is clear, easy to read, and concise. Readers want to instantly know if this is going to be worth their time or could they figure it out on their own faster. This brings up the importance of visual appeal. Readers will think that a document is easier if it looks easy to read and clear. Campbell says that there are twenty different design elements: sentence length, paragraph length, line spacing, typestyle, typeface, emphasis, paragraph spacing, justification, indentation, margins, headings, graphics, visual weight, contrast, color, symbols, columns, lists, forms, and white space. She brings up the importance of avoiding visual clutter, which she compared to an attic or garage that no one wants to look at so they shut the door.
Campbell tells the reader that the human brain can only retain seven different items at once but can only clearly distinguish between three of the seven items. That is way the rule of three was created. The rule of three is based on not using more than three different design elements in one document.
Eye movement is an important concept to understand. Campbell talks about the limits that the eye has:

Takes in approximately forty characters at once.
Takes in three or more words per second.
Reads two or more words at one time.
Moves from top to bottom and left to right, in a zigzag or Z pattern.

Barker Chapter 6 - Planning and Writing Your Documents

2007-10-08T22:14:00.000-05:00

Barker begins this chapter by stating that there are nine phases in the documentation process. He says that the key to producing quality documentation is to follow a process. The process Barker describes in this chapter has phases that build on the previous one, and each imply testing procedures and ways for documentation managers and writers to check their progress.

1. Start the Project
The first phase Baker explains is to start the project. He says the start of a project is for you to get to know the software you’ll be writing about. Also, most software documentation is created by two types of teams: development and writing.

Barker then goes on to describe the two teams in greater detail. The development team develops the entire product: software and documentation. These teams are normally assembled from a group of professionals with varied skills. The following is a list of members you can expect to find: Product Developer, Project Manager, Market/Systems Analyst, Technical Specialist/Programmer, and Documentation Specialist. The writing team just develops the documents. The writing team deals with developers, programmers, and others involved in the whole project, but these programmers and developers serves as subject matter experts and not members of the immediate team. The following is a list of members you can expect to find on a writing team: Manager, Lead Writer, Writer, Editor, Graphics Designer, and Tester.

Barker also discusses the need for preliminary research. The users are analyzed and the justification for software gets written down in what are known as project documents. Depending on the company or organization developing the software, you will find variations of the following types of documents: Project Plans, Program Specifications, Market Analysis, Information Plan, and Management Plan.

Barker then shifts his discussion to choosing online media and the special considerations for developing help systems. He says it basically follows the nine-step list, but it often includes extra steps because of the technical aspects of help. The development stages mirror the development of a user’s guide except for these key differences: user analysis, mastering the authoring environment, linking to the software program, testing the help system, and testing in different user environments. Barker provides a brief overview of the process of developing online help. He writes that you must first select the right authoring environment. He gives a list of some of the most well-known authoring environments and suggests looking at the following features to decide which one is right. These include: single-source capabilities, authoring features, management features, and types of help formats supported.

2. Perform the User Analysis
During this stage, Barker writes that you research a number of elements pertinent to effective software use, mainly focusing on the workplace activities of your users that involve software. You use the elements described in chapter 5 to properly determine the user type. The activities in the user analysis should allow you to group the program operations for your table of contents. A default user table of contents describes the functions of the program but fails to reflect anything about the use of the program for meaningful workplace activities. On the other hand, the task-oriented version is grouped by workplace activities and focuses on a process of learning.

3. Design the Documents
Next, Barker states that during the design phase, three types of documents forms are applied to the user’s needs: tutorial, procedures, and reference. Also, at this stage, the titles of the documents are written and you finalize what they will look like. For online help, you decide the types of products you will produce. During this phase you set out the content and look of your document, but decisions at this phase are important for planning, and may change over time.

4. Plan the Documentation Project
Barker then goes on to describe planning the documentation project. If you are managing a project you need to know how to write a project plan so your team members can have a guidepost and keep up with deadlines. A well-organized and quality document is the result of a carefully planned project that makes the most of the users, the writers, and programmers on the team. The key document to organizing a documentation project is the documentation plan. The project plan culminates your research and design work on a project.

Barker suggests making a list of project events and sharing it with the other people on your team for approval and input. He also discusses the three main parts of a project plan, which are: schedule of events for completion of your project, plans for using resources, and time/page estimates. When scheduling a documentation project, you should include the overall phases as well as the following six kinds of events: meetings, deadlines for drafts, project report due dates, test completion, review deadlines and edits. You will also need to plan human and material resources. To assign people to tasks, Barker suggests keeping in mind the following characteristics: writing skills, editing skills, software tool skills, experience with the subject matter of the program, knowledge of the user and the user’s workplace, and familiarity with the development environment. Barker gives an example of what to follow for estimating time/page estimates, but he notes that a number of variables could change this estimate. These include: type of documentation, availability of information, experience of writers, and reliability of the program.

Barker notes that your documentation plan should undergo thorough testing and review by managers, clients, and users. The documentation plan gives you the opportunity to hold a user and technical walkthrough.

5. Write the Alpha Draft
According to Barker, the alpha draft represents your first complete document, including all the front matter, text, graphics, appendixes, indexes, and associated documentation set materials. This draft is tested, reviewed and edited.

6. Conduct Reviews and Tests
Barker writes that since your alpha draft contains all the elements of your product, you can send it out for review. You can also design usability tests. Information obtained in this step provides feedback for the next draft of the set.

7. Revise and Edit
The reviews and the tests from the previous step provide feedback from external sources. Barker notes that revising and editing also allow you to submit your work to an editor that checks for accuracy on many levels. Barker notes that more editing and revising documentation and online help is covered in Chapter 9.

8. Write a Final Draft
Barker writes that if you do the previous two steps thoroughly, you fill find that your document improves greatly at this stage. Barker notes that the final draft of a help system mainly consists of preparing the help file for distribution with the finished program.

9. Conduct a Field Evaluation
Barker explains that after the user has installed and operated the program, the last stage of the development process happens: the field evaluation. This test allows you to gauge how well your manual met the task needs of the intended user. To conduct a field evaluation of a help system, you can use feedback links in the HTML system and use email links.

Barker then goes on to discuss the two main types of projects: stand-alone and development projects. He writes that a stand-alone project is where you are assigned or contracted to write documentation for a software application that has already been written or is being revised. The development project occurs in organizations that create software as their main products. There are differences between the two in three areas: team structures, work processes, and kinds of development documents required.

Next, Barker describes the differences in detail. He says that in stand-alone projects, writers have the entire program at their disposal before they start. In development projects, the writers are involved in the project from the design stages onward so they have more input into the usability and interface of the project. Also, in stand-alone projects, writers follow the nine-phase process listed above. On the other hand, in development projects, they follow one of three main development methodologies, which are: the waterfall method, the rapid-development method, and the object modeling method. Barker gives descriptions of each method. The waterfall method depends on understanding the users’ requirements at the beginning of the project and then carefully designing a system to meet them. Ideally, each phase is done before the next begins. The rapid-development method uses a process of usability testing and prototyping to test designs out during development. Once the right design is found, the program is complete. User requirements are refined as the product unfolds. The object-modeling method uses a complex system of symbols and descriptions to create an abstract design for the system that can be turned into software and documentation with a high degree of consistency.

Barker concludes this chapter by discussing the documentation plan. He says that you should set for yourself a number of goals, among them efficiency and logic in the whole process. You should also make sure your documentation plan is persuasive, and Barker lists the following strategies to help with this: use an executive summary, have a goal orientation, do the math, and show a team orientation. He also suggests ways to make the documentation plan easy to follow. These include: standardizing your terminology, including sample pages, and not stinting on detail in the outlines. Barker also includes the two parts of a documentation plan, which are describing the manual and help, and describing the documentation project. The first part describes the design plan, while the second part describes the project plan. Barker adds that your design plan should describe the users, set out the documentation objectives, provide outlines of individual documents and lay out individual documents. Finally, Barker ends the chapter by giving an outline for a documentation plan.

Nancy Allen et al. - Collaborative Writing

2007-10-03T00:43:00.000-05:00

What Experienced Collaborators Say About Collaborative Writing
Nancy Allen, Dianne Atkinson, Meg Morgan, Teresa Moore, and Craig Snow

Introduction

The article begins by explaining how recent research into writing on the job has uncovered the interesting issue of collaborative writing. There exists very little research focusing specifically on this topic, however. Information about collaborative writing, the authors state, is “fragmentary and unfocused”. The authors then cite studies that allude to collaborative writing in the workplace. These include research by Paul Anderson; Faigley and Miller; Odell; Paradis, Dobrin, and Miller; and several others. The peripheral nature of collaborative writing information in these studies cause the authors to state, “from these studies we gain little in the sense of the details or range of variation in the processes collaborative writers user, few clearly articulated reasons for employing a collaborative effort…and no coherent evaluation of collaboration from the writers themselves.”

The scant research that does exist on the topic of collaborative writing reveals a range of activities in which these writers engage. These include scenarios such as staff-written/supervisor-edited documents, collaborative planning with individual drafting, individual drafting with collaborative revising, and coauthoring, among others.

These many different forms of collaborative writing compel the authors to clarify their definition of the topic. They cite a paper by Wiener, who distinguishes between “group work”, a basically individual effort that is supported by a group, and “collaboration”, in which all group members share responsibility for the final product and must achieve consensus in order to produce it. This is the form of collaboration on which this article chooses to focus.

The article identifies two problems in reviewing the existing research. The collaborative writing process itself is poorly understood, and studies have not focused specifically enough on collaborative situations involving group authorship. For this reason, this study focuses on answering the following questions:

· What kinds of people form collaborative-writing groups and what kinds of tasks do they undertake?
· What are the writing processes used by experienced collaborators?
· What significant group processes emerge in collaborative-writing groups?
· How do experienced collaborators feel about the costs and rewards of collaboration?

Methods

In this section the authors discuss their research methodology, describing the project as “an exploratory study of the experiences of active collaborative writers from the business and professional worlds.” The participants were chosen to represent a wide range of collaborative settings and projects. The authors go on to provide specific demographic data about the subjects. They then discuss the structured interview form that they made use of. This form began by soliciting demographic information about the participants, then when on to ask questions about the membership of the collaborative writing groups that they have been a part of, the roles and contributions made by members, the writing process used, the types of group interaction that took place, and their overall evaluations of the experience as a whole. These questions were asked over the course of a two hour interview.

In the first stage of analysis, transcripts of the participants’ responses were referenced to produce basic demographic profiles of the members and their projects. In the second stage, the participants detailed observations and evaluations were collated.

Research Findings

The authors concede that their small sample size makes the information gleaned from their study incomplete. Demographically, the participants represented a wide variety of collaborative writing tasks, covering many different forms of professional documents. They also note that participants tended to want to talk about projects that they deemed successful, versus failures. The types of groups with which the participants had worked were diverse in nature in that some were made up of members with very different backgrounds and skills, while other groups had very similar membership. Most groups knew the type of document they would be producing and its general format, while others had higher or lower levels of task restriction.

The group writing processes that the participants engaged in always began with collaborative planning activities. This was usually followed by relatively independent research and drafting. Different participants reported different scenarios. Some produced drafts after heavy group planning, then revised based on group discussion. In some groups, everyone produced a draft, and in subsequent meetings members attempted to merge them. In other groups, the members contributed sections based on their specialties. Sometimes group members attempted to write collectively, word-for-word, a practice which often led to frustration.

Most participants reported significant interaction between group members early in the project, usually face-to-face. The article identifies three important aspects of group interaction:

Group as First-Line Audience

The group often served as an initial audience for the piece that they were writing, unconsciously or consciously.

Group Conflict

Conflict seems to be a given with collaborative writing (or as one respondent put it, “collaborative fighting”), but can benefit the process in many ways.

Computer-Aided Interaction

Computer-mediated communication was not nearly as prevalent at the time this article was written as it is now, however, some of the participants in the study had made use of computers to communicate with other collaborators on writing projects. This included both text-based communication, and sharing of drafts.

Decision-making power in the collaborative writing groups was shared in that anyone in the group could contribute suggestions or object to any idea. This power, however, was completely limited to the writing task at hand. There was a great deal of commitment to the process and the group among members.

Most of the groups were structured around group leaders who primarily seemed to serve a coordinating function. However, there were leaderless groups which prove that this is not necessarily a defining feature of collaborative writing.

Most respondents greatly appreciated the benefits of collaboration, finding them well worth the costs of time, energy, and ego. The documents that they produced collaboratively, they rated as “satisfied” or “very satisfied”. The subjects all recommended collaboration.

Discussion

The research results suggest three important points.

Functions of Conflict

The authors present several studies that support their participants’ suggestions that conflict increased group creativity. These include Janis, Weick, Rothenberg, and others. “When the group can tolerate some disharmony and work through divergent opinion to reach a consensus, their work is enhanced,” the authors conclude.

Distinguishing Shared-Document Collaboration

Here, the article presents a new term for describing a certain form of collaborative writing: shared-document collaboration. Such writing must involve production of a shared document, substantive interaction between group members, and shared decision-making power and responsibility.

There are many advantages to forming collaborative writing groups. The authors found that such groups are formed primarily because of the size of the task, the scope of the task, or a desire to merge divergent perspectives.

Questions for Further Research

The authors conclude their article by conceding its exploratory nature, and reiterating that their small sample (many of whom have academic affiliations) can only yield partial results. They also point out that since their subjects chose to speak mainly about successful projects, they have little data regarding failed collaborative writing projects. Future research on this topic could explore the influence of leadership styles, the use of multiple group types and writing processes on a single project, new technologies, and the interaction between organizational hierarchies and the hierarchy of collaborative writing group members. From business to academia, more information on collaborative writing would be immediately useful. The authors hope that they have pointed the way to future research.

Barker - Chapter 5 - Analyzing Your Users

2007-10-01T23:47:00.001-05:00

Writing Software Documentation: A Task-Oriented Approach
Thomas T. Barker

Chapter 5 – Analyzing Your Users

Intro

Barker begins the chapter by giving an overview of what user analysis entails and why it is valuable. User represents the “basic research phase of the documentation process”, and involves “contact with persons who might use the software that you want to document. It involves inquiry into eight areas:

1. Tasks and activities the user will perform
2. User’s informational needs
3. User’s work motivations
4. Level of the user’s computer experience
5. User’s knowledge of the program’s subject matter
6. User community
7. User’s learning preference
8. User’s usage pattern

The answers to these questions will assist throughout the documentation process, informing the goals for the documents and what they will cover.

1. Choose Users Carefully

You begin this process by listing every potential type or group of potential users of the software as possible. You can then narrow down this list to those whom represent typical users and with whom you can form a working relationship throughout the documentation process. This selection process should involve consideration of each user’s unique culture.

After assembling this list of users, you will conduct a series of interviews with these individuals to build a list of common job tasks that would benefit from documentation.

2. Anticipate Transfer of Learning: Study Users Before and After Tasks

You should begin by determining the activities of users, “without the benefit of your program”. When you understand about the duties and skills of your users, you can craft your documentation in such a way that facilitates the transfer of these pre-existing skills to the operation of your software.
It is also important to build up a repository of tacit knowledge about users, which includes all of the small facts, attitudes, artifacts, interactions, and values that guide them in their job duties.

3. Research Professional Behaviors

In situations where direct user contact is impossible or insufficient, it is possible to research professional behaviors to construct a “mock-up of the user”. There are many resources for learning about the job duties of individuals in a particular position or industry, including occupational guides, industry-specific guides, placement services, or company job descriptions.

4. Write Use Cases

Use cases are descriptions of typical job scenarios, based on the tacit knowledge that comes from uncovering the “motivations, behaviors, values, and knowledge pertaining to your users that might not be visible on the surface.” By employing use cases in your documentation, you provide role models for your users. Use cases can also be included in the documentation plan to illustrate the types of activities that will be supported.

Work flow diagrams, which graphically depict organizational processes, are often a useful accompaniment to a use case. Barker also suggests that you should be mindful of your limited resources, and restrict your documentation accordingly.

5. Plan Interviews Carefully

Effective software documentation should “encourage [users] to learn the features of the program and put the program to useful work.” To this end, interview questions should involve users in the whole documentation cycle, using a usability approach.

Familiarity with the developers of the program and the program itself should help inform the questions you will have for users. Investing time in an interview plan can greatly increase their productivity. General steps for interview planning include:

1. Do preliminary research into the user’s job and programs already in use.
2. Review the software program and indentify the issues.
3. Establish the scope of your interviews.
4. Make a list of interview questions.
5. Get permission.
6. Set up and interview schedule.
7. Plan a follow-up.

Barker also recommends attempting to assess the verbal style of the users and reflecting it throughout the interview process to solicit better answers.

In addition to interviewing, observation can be a useful tool for gathering data about your users. This involves shadowing users at their place of work and recording their various actions, while taking care to avoid:

· Getting too involved – such that you distort their activities.
· Not getting involved enough – such that you focus on the wrong details.

Questionnaires are also valuable in that they allow you to gather information from a variety of users, increase the chance of identifying unique concerns, and identify wide patterns of use. For best results, these questionnaires should make use of open-ended questions, include clear instructions and plenty of room for filling in responses, and avoid negatively-worded questions.

6. Involve Users in All Phases of Project

A full user analysis should involve users in every stage of the documentation process, including writing, reviewing, and testing. This results in many benefits, including:

· Increased accuracy
· More appropriate information
· Increased usability
· Improved relationships

The relationship between the documentation writer and the users is an important one. Including them in the process yields valuable information regarding their specific situated action in the organization. This allows you to become a user advocate, bridging the gap between the software program’s users and developers. This relationship will also benefit from embracing the work culture of the users.

Conducting focus groups is another way to involve users in documentation, and are a good way to spark new ideas. Tips for conducting a successful focus group include:

1. Locate potential participants.
2. Develop and administer a telephone screening questionnaire.
3. Confirm invitations in writing.
4. Draft open-ended questions and follow-up questions, then revise.
5. Plan any hands-on activities.
6. Make reminder calls.
7. Pilot-test the questions with one or two group members.

Encouraging user participation in this way helps “extend the possibilities of user-centered design.”

7. Identify Document Goals

It is important to communicate your documentation goals early in the process. These consist of statements expressing specific objectives describing how the documentation will encourage users to learn the program and use it effectively. “The clearer your objectives,” states Barker, “the better the chance that you will achieve them.”

8. Tie the User Analysis to Documentation Features

It is important that the features that you document are chosen based on specific user needs. By tailoring this information to specific users, a more usable document results.

Discussion

User analysis is of central importance when composing task-oriented documentation. It incorporates the users’ workplace context, personal needs, organizational goals, work culture, and many other factors. This can assist you in a number of ways, such as by revealing ways in which users will use the software, providing scenarios and examples for use in tutorials, and identifying potential topics for testing, among others. Ultimately, a well-done user analysis will help “unify your document set”.

Software use is always situated in a user’s workplace and cultural context. Effective documentation will take this into account, and reflect “the user integrating the program instead of just the program.” Eight questions that help provide this tacit knowledge include:

1. What tasks will the user perform with the program?

Knowledge of job roles provides a starting point in describing user actions. Workplace activities exist in a context of information. Barker suggests focusing on a few key tasks to use as cornerstones within your documentation.

2. What are the user’s informational needs?

Often, software users may require some knowledge that is outside the realm of the program itself in order to use the program effectively (e.g. graphic design principles for a user of page layout software). It is useful to identify any such information and direct your users to the relevant resources.

3. What are the user’s work motivations?

Awareness of how users’ tasks shape their information and communication needs will help you to identify users’ underlying motivations. Interface elements should therefore take this awareness into account, and be arranged into “meaningful sequences leading to an objective” that is of value to the user.

4. What’s the user’s range of computer experience?

There are many differences between novice, experienced, and expert software users. It is important to pay attention to these differences and target your documentation to the learning patterns of the appropriate audience, or multiple audiences, when necessary.

5. How much does the user know about the subject matter of the program?

Subject matter knowledge influences the amount of supporting detail required when describing operations. This professional knowledge is also referred to as domain knowledge.

6. What’s the user’s workplace environment?

Various forms of user communities can often provide a great deal support to software users. These include help forums, special interest groups, newsgroups, user groups, web resources, newsletters, third-party documentation, FAQs, web rings, and mailing lists. You should strive to direct your users to these resources when appropriate.

7. What’s the user’s preferred learning preference?

Individuals accumulate knowledge in different ways based on a variety of factors. Whether the information is being delivered by an instructor, manual, or computer-based system, it is important to take into account factors such as the learning setting, the source of information, variations in information delivery, and the various forms of media used.

8. What’s the user’s usage pattern?

Usage patterns describe how users interact with the software over time. These can be: regular – involving daily use, intermittent – regular and frequent but at irregular intervals, or casual – an immediate need for use exists, but with little or no formal training yet received.

Barker concludes the chapter with a glossary of terms, a checklist for performing a user analysis, and some case studies with which to practice.

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

2007-10-01T11:15:00.000-05:00

In chapter 5, Campbell begins by discussing how to choose a format for policies and procedures. The best format depends on whom you’re writing for, what kind of material you’re dealing with and whether management accepts the format.

When determining your format, you should first ask yourself who your audience is. Campbell writes that certain formats are better for particular types of people. Engineers, scientists, and those with a technical background prefer flowcharts, while they might confuse other people. Readers respond better to formats they’re familiar with. However, unfamiliar formats don’t necessarily mean a bad choice. If the old format is ineffective, it is wise to switch. If using an unfamiliar format, Campbell suggests making time to introduce and explain it to your readers. Sometimes an organization requires a certain format, but if it seems confusing, occasionally organizations will make a parallel document, which is more user-friendly.

Another thing Campbell says to consider when formatting your document is the material. The nature of the information narrows your format options. Safety procedures require absolute clarity, so you want a format that is clear at first glance. In this case, a standard narrative format won’t help the reader much, and a flowchart could work much better. Campbell writes that you should examine the nature of the material closely before you settle on a format.

The final aspect of format consideration is management. Since upper management authorizes the policies and procedures, they must also understand and support the document and its contents. Campbell writes that you must ensure management’s comfort level, which is just as important as that of other readers.

Campbell then goes on to discuss how to decide a page layout for your document. She writes that the page layout gives the reader certain information about the policy or procedures, such as title, number, or effective date. This information is usually found in the header. A full header with all of the information typically appears on the first page, and a shorter version appears on the remaining pages. If the information is substantial, it is sometimes split into a header and footer. In other page layouts, certain parts of the text are standardized and are put immediately preceding the policy or procedure but outside the header. Campbell writes that the amount and types of information you standardize are up to you. The goal is to keep the document simple so the standardized information doesn’t detract attention from the policy or procedure itself. Once you decide what the readers need to know, you decide where and how to place it on the page.

Next, Campbell discusses choosing a format among the options. She writes that once you decide on a page layout, you are ready to choose a format from the main text. The primary options are: narrative, outline, playscript, or flowchart. These options are often used in combination with each other. The secondary options are: question and answer, troubleshooting, matrix table, and list. They are known as secondary because they can’t be inserted into the main document format. Campbell notes that once you choose a primary format, you must use it consistently throughout your document.

Campbell then goes on to discuss the primary formats in-depth. She first discusses narrative, which is the standard sentence-and-paragraph style. Standard narrative format is usually a single column, but two-column formats are also common and are used to break up sold horizontal lines of print. Narrative format is used more for policies than procedures. Campbell notes that narrative is not effective with complex, difficult, or lengthy material.

The next primary format Campbell discusses is the outline, which is a variation of the narrative format. The text is separated into shorter sections and subsections. These sections are labeled with numbers, letters or alphanumeric combinations. Campbell writes that the outline formats can vary widely, and that the format depends on the material you’re working with. She also notes that it is used in both policies and procedures because it is easy to follow.

Next, Campbell writes about the playscript format, which is great for procedures that involve more than one person or department. In the simplest form, a playscript has two columns. The first column tells who’s responsible while the second column describes what’s required. This format can be adapted for more complex procedures. The playscript is clear and provides an instant visual clue to the reader so they know what’s relevant to them. Campbell notes that when you use a playscript for the first time, you should explain it briefly to the readers.

The final primary format Campbell discusses is the flowchart, which is a diagram of process that uses symbols and arrows to indicated flow and action. Flowcharts are more commonly used in procedures than policies. Campbell notes that a danger of flowcharts is that they can quickly become cluttered and hard to read.

Campbell then goes on to discuss using secondary formats. The main purpose of these formats is to deal with other possibilities that may arise and special conditions that may exist. Campbell begins by discussing the question and answer format, which are used in both policies and procedures. They contain questions that a majority of readers might ask and are designed to simulate a personal conversation.

The next secondary format Campbell discusses is troubleshooting, which are used primarily in procedures so users aren’t forced to reread the entire document to get help when there’s trouble. Campbell writes that troubleshooting sections are often presented in chart format so the problem can be solved quickly.

Next, Campbell discusses matrix tables, which connect one variable to a second variable. She writes that matrix tables are a good format when readers need to refer repeatedly to the information periodically over time because they eliminate the need for constant rereading and searching.

Campbell then goes on to discuss lists, which should be used often because the eye loves lists. Campbell writes that lists break up the denseness of the printed page and let the eye skim quickly. An indented group of related items is known as a displayed or vertical list, but there are also other types, such as paragraph, nested and parenthetical. Lists allow you to use shortcuts what would sound odd in a regular sentence. These include leaving out the subject and starting with a verb, leaving out articles, and using partial sentences or only key words. Campbell notes that the main purpose of the list is to shorten, organize and clarify.

Campbell concludes this chapter by writing about combining formats and experimenting with different formats. She notes that you can switch among the formats for clarification, but to be cautious as to not overwhelm the reader. The formats should be experimented with in a search for better ways to communication important information with clarity and speed.

Campbell - Chapter 4: What’s the Best Way to Word This?

2007-09-26T23:02:00.000-05:00

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

Nancy J. Campbell

Chapter 4 - What’s the Best Way to Word This?

Technical vs. Narrative Writing

Campbell begins the chapter by attempting to explain the technical writing style. The writing that most of us learned in school, she terms “narrative” writing, a style which makes use of “complex grammatical structures” and is often descriptive, lengthy, and complicated. Policies and procedures, she argues, should employ a form of technical writing that emphasizes clarity and speed of transmission.

The Old Rules

In this section, Campbell reiterates her belief that our educational system equates verbosity with quality. Policy and procedure authors, she concludes, must shed this inappropriate mindset.

The New Rules

Effective policy and procedure writers, Campbell asserts, adhere to the maxim, “Simple is good.” She decries padding, complex sentence structures, and fancy vocabulary.

Being A Word Miser

In the pursuit of verbal simplicity, Campbell suggests that text should be limited to only those words absolutely necessary to convey the intended message. She offers several tips to help in achieving this goal:

Think in Ones

Eliminate unnecessary adjectives, prepositional phrases, and extra clauses, using only those words necessary to convey your main point.

Dump Pompous, Stuffy Language

Eliminate “windy, stiff language” by following Campbell’s word miser rules, to be discussed later.

Speak to the Reader

Try to write as though you were speaking to your reader in person. Avoid the “flabby, excessive writing”, that comes from dressing up common words (e.g. use→utilize, start→initiate, etc.).

Follow the Word Miser’s Rules to Live By

The use of active voice clarifies roles, and writing in the present tense gives a desirable sense of immediacy. This is true, suggests Campbell, even when these techniques lead to the use of improper grammar.

Be an Accurate Word Miser

Here, Campbell reminds her readers that brevity should never come at the cost of clarity. When cutting words, do so judiciously to avoid introducing uncertainty and confusion.

The Word Miser’s Rules to Live By

Here, Campbell summarizes her suggestions in a list of 17 rules for effectively communicating policies and procedures. Many of these are accompanied by examples.

1. Use common words and phrases.

2. Use one- and two-syllable words.

3. Get rid of windy phrases.

4. Get rid of redundancies.

5. Get rid of empty phrases.

6. Eliminate all unnecessary adjectives and descriptions.

7. Limit the number of clauses and phrases, and keep them short.

8. Use short sentences.

9. Use short paragraphs.

10. Use one-sentence paragraphs.

11. Keep phrases and clauses short.

12. User transitions at the start or sentences and paragraphs to tell readers what’s happening next.

13. Use lots of lists.

14. Use active voice.

15. Use present tense.

16. Start with an action verb.

17. Use standard word order of subject-verb-object.

Being a Word Master

In this section, Campbell offers additional tips for becoming a “word master”, or “one who uses words with precision and respect”. These include:

Say What You Mean and Mean What You Say

It is important to be mindful of the vast range of possible misunderstandings inherent in even the simplest of phrases. This requires precision in communication, which may trump the goal of brevity.

Use Specific Language

Policy and procedure writers should avoid words that invite varying interpretations. These include “weasel words” such as “may, might, could, should, etc.” Each of these words has a precise meaning that must be fully understood.

Developing a Rhythm

Here, Campbell introduces the concepts of consistency and parallelism, which contribute powerfully to reader interest and comprehension.

Consistency

Varying words and terminology can confuse readers, so use terms consistently throughout a document. This is one area in which creative wordplay can degrade clarity.

Parallelism

Parallelism simply refers to the technique of using the same grammatical format for like items. Varying grammatical constructs makes instructions awkward to follow.

Being Correct

It’s extremely important to avoid mistakes in grammar or usage, states Campbell. Such errors can lead to confusion, misinterpretation, and mistakes. To help avoid these issues, policy and procedure writers should refer to style guides as needed.

Considering the Reader

This section offers information on writing in such a way that is relevant to one’s readers. It assumes that one has performed the audience analysis.

Don’t Assume Anything

Do not overestimate the knowledge or experience of your audience.

Look at the Reader’s Experience

Reexamine your audience analysis, and in most cases, target your writing to your most inexperienced readers.

Use Jargon Carefully

Some considerations regarding jargon include:

Even experienced users may not be familiar with it.
It can be cumbersome and difficult to understand.
It can be faddish and pompous.

Distinguishing Between Users and Readers

When writing policies and procedures, give precedence to the needs of your users over those of your readers.

Calculate Reading Level

Make use of software-based or manual reading level calculations to ensure that you are writing at an appropriate level for your audience. This is frequently in the range of a 6^th-8^th year reading level.

Word Documents Carefully

Using words that provoke unpleasant reactions will reduce our audience’s receptivity to your message.

Using Special Techniques for Procedures

Special technical writing techniques exist that can help maintain a high level of clarity when writing, thereby reducing the serious risks associated with unclear policies and procedures.

Start With an Action Verb

Policy and procedure users are generally looking for an answer to the question, “What do I do?”. Beginning one’s sentences with action statements offers them a clear reply.

Use One Action per Sep

Steps that contain more than one action “confuse the reader and bury the message”. Most procedures should be broken down into their most basic, individual steps. Exceptions to this may be made in cases where the nature of the procedure is such that combining steps increases the clarity of instruction.

Assign the Action

When there are multiple actors involved in a procedure, it is important to clearly state who is responsible for each step of the process. Avoid using indefinite pronouns.

Pack a Sentence

Readers tend to remember the first and last parts of a sentence best, so in some cases it is useful to arrange your words to capitalize on this phenomenon.

Choose the Right Format

Adhering to strict format guidelines can help a policy and procedure author adhere to all of these suggestions automatically.

Tools and Resources

Campbell concludes her chapter with a collection of lists, tip sheets, guidelines, and formulas to aid in the construction of policies and procedures.

Barker Chapter 4

2007-09-26T12:50:00.000-05:00

Writing to Support – Reference

Barker discusses the third level of the levels of support, reference documentation, also known as support documentation. Barker defines and explains the purpose for the three types of reference information:

Appendices: which allow the documenters a place to put all the highly detailed, technical information that the technical users would want to use in the workplace. The appendix is relevant and useful but may not be essential to all users. Some examples of items in the appendix are:

Error messages and explanations of how to recover from them.
Filenames and extensions of files associated with the program.
Troubleshooting tips.
Matrixes of compatibility with other programs.
Charts showing program key combinations.
Printer driver charts showing capabilities with various printer brands.
FAQ.

Update Information Sections/Readme Files: Consist of text files that accompany programs either with an additional disk or download from an internet site. They serve the purpose of informing the user of new information, installation details, last minute changes, new features, etc.

Job Aids: also known as job performance aids, are shorter forms of reference documentation that include keystrokes, definitions, brief processes, command summaries and other information useful to users. The purpose of the job aid is to provide useful information at the point of need. They consist of a number of forms such as; keyboard templates, cheat sheets, laminated program cards, quick reference cards, and other forms. Another variation of the job aid is the innovative forms: Flipcards, the purpose of the flip card is make it easier for the user to simply flip through the information he or she is searching for.

Innovative Forms: Flipcards This section Barker also discusses as an easy to follow format it is technically classified with the job aids. The flip card is valuable because:

Easy to read
Contains a surprisingly large amount of information
Colored headings
Unique and interesting
Affords easy access to information.

Barker also discusses the importance of what to include in your reference guide, he breaks up the reference specifications into three main groups:

Commands: refers to all the instructions the user uses to make the program work.
Information about the commands would include:
Meanings of special function groups
Explanation of set commands
Definitions and use of format commands
Special procedures for using utilities
Explanations of toolbars
Definitions of macros

Interface Elements: Refer to the parts of the screen that the user sees and has to manipulate in order to use, these include:

Explanations of menus
Definitions of keys
Labels of screen regions
Explanations of rulers

Definitions of Terms (Glossary)

Concepts that underlie the software
Terms relating to the subject matter of the software

Barker also discusses the importance of organization either alphabetical or menu-by-menu. Menu-by-menu may have more advantage because the user is used to seeing that format. He also states that you should explain to the user how and when the reference guide should be used. It is different from teaching or guidance level of support, it is there to inform the reader not to give a “how to”.

Contesting the Objectivist Paradigm: Gender Issues in the Technical and Professional Communication Curriculum

2007-09-17T22:00:00.000-05:00

In her article “Contesting the Objectivist Paradigm: Gender Issues in the Technical and Professional Communication Curriculum,” Lee Brasseur discusses the different aspects of her master’s level “Gender Issues in Technical and Professional Writing and Communication” class and how she is working toward a socially responsible discourse model.

Brasseur begins her discussion by giving a brief history of language practices. She says that scientific language has been about clarity and conciseness, but that it often hides the complexity of the social environment. Scientific rationalism reflects a view of subject/object ideologies, which assume that one’s position is impartial because the human agency is self-defined and self-motivated. Language practices influenced by this outlook promote a disregard for any culture or cultures outside the dominant one. The dominant group naturally imposes an order upon the more subordinate parts of the culture. Science and technology have reflected the views of the dominant group within its culture, which is a “masculinist model of human experience which assigns goodness to certain valued ‘male’ traits such as rational thinking and objectivity” (477). The current understanding of rational judgment is defined by this group’s ideas about human behavior. However, this paradigm is shifting as more critics warn us about its problematic theories and practices. These critics hope to replace the current discourse model with one that emphasizes multiple positions and moves toward a new paradigm of “objective” discourse.

Brasseur then goes on to discuss the need for a course devoted to gender issues in technical communication. Her goals for the class are to communicate to future technical communicators the value of critiquing the traditional technical discourse model and its reliance on gender-based assumptions. She believes that a course entirely devoted to discussing gender issues will help students study the theoretical and practical information that can strengthen their resolve to change outdated and ineffective paradigms. The students in her class, she believes, will learn that although some of the current discourse models in technical communication are effective in an organization, they may also contribute to communication that limits the capacity to promote change.

Next, Brasseur highlights the two course goals for her “Gender Issues in Technical and Professional Writing and Communication” class. The first goal is to introduce students to the “problems inherent in gendered assumptions about rationality and objectivity, as well as the role of feminist theory in addressing these problems” (479). While the second goal is for students to “gain practical experience in addressing these problems by conducting ethnographic workplace studies” (479).

The assigned readings for Brasseur’s course include those that would present oppositional or essentialist views of feminism, and those that promoted situated knowledge. These texts focus on the societal differences between men and women, as well as the different ways of thinking and understanding. Brasseur discusses the difficulty in selecting textbooks, and says her final decision was based on the diverse background of her students.

For assignments, Brasseur’s students responded in essay format to one or two questions that were meant to help them sort out what they had read. In addition to the assigned readings, Brasseur also had her students select their own readings and lead a class discussion about what they had found. To complete her second goal, the students designed a workplace ethnographic study on a topic related to gender issues.

Brasseur then goes on to describe her syllabus for the course. The syllabus consisted of three units, which focused on specific goals for the class. The first unit was centered on the larger problems of discourse models with privilege objective voices. The second unit provided an examination of two central issues underlying this communication model: “the important role that naming plays in determining how we think and communicate our sense of reality,” and “how permanent positionings of domination and subordination underlie any problematic subject/object ideologies” (481). The third unit addressed the social construction of the workplace and promoted the examination of traditional forms of oral discourse. In addition to the three units, the syllabus listed student-selected readings that focused on the topic of women and technology.

Next, Brasseur discusses an essential part of her course design, which is moving from theory to practice. Through the assigned readings, students became aware of the different theories related to technical discourse, and from these readings, they were able to design their own workplace study to help them gain a personal understanding of the complexity of organizational roles of rationality and objectivity. Brasseur taught her students how to perform proper ethnographies, which take place in a “real world” setting and instead of having the traditional hypothesis, begin with a series of general questions. Even though these studies weren’t performed in a short-time period, Brasseur believed they were useful because they offer a different kind of picture than a study performed in a laboratory. The students performed a variety of studies including some with educational settings, one in a bank, and one in a hospital. Brasseur says that greatest value of the studies was that they provided direct examples of gender-based assumptions for her students.

Brasseur concludes her article by discussing the student and instructor evaluations for the course. She says that overall, the students’ responses were positive, and that the only real complaint was the amount of reading. The comments from her students included how they couldn’t imagine a degree without this class and how the class helped them see the relation of feminist theory to technical writing. Brasseur also includes her own set of comments for what she would like to change about the course in the future. These comments include a change in the required texts, and to allow students to choose any workplace situation to study, not just gender. Brasseur ends her discussion by stating that traditional technical models of discourse are normally taught, and that her class provides a different way of thinking about discourse models.

Campbell Chapter 3 - Isn't There a Law Somewhere?

2007-09-17T15:00:00.000-05:00

In this chapter, Campbell discusses the legality and consequences of policies and procedures. She starts by stating that as a writer, you have to be familiar with the restrictions imposed by the laws to avoid your organization being sued.

Next, Campbell states some of the reasons you can and will be sued for. They are:
• If the procedures used by customers or employees are unclear, imprecise, or poorly worded.
• If your policy or procedure violates some law or legal precept, intentionally or unintentionally.
• If the wording of your policies and procedures restricts the organization’s ability to act.
• If you have written policies and procedures but don’t use them or don’t enforce them consistently.
• If you fail to state who is responsible for or what the consequences of noncompliance are.
• If your policies or procedures are incomplete, in improper order, or inaccurate.

Campbell then talks about special obligations needed to prevent users from understanding your policies and procedures. These are language barriers and literacy problems. She says that for literacy problems, to make the document written at an appropriate reading level. For language barriers, the document may need to be translated.

Then, Campbell goes on to discuss the different types of violations. The first is a tort, which is simply a wrongful act, one that violates a duty imposed by law, and is grounds for a civil action. Campbell says that you may face court challenges for a variety of reasons including: operational policies and procedures violate safety regulations or pollution laws; administrative policies and procedures violate fiduciary laws or fraud statutes; or if your personnel policies and procedures violate civil right laws or public policy, which refers to actions that may not have any direct statutory protection but are generally recognized as being in the public interest.

The next type of violation that Campbell discusses is negligence, which is the failure to exercise reasonable care in instances where such care is a duty under the law. These claims tend to affect procedures more than policies, but they can happen in either case. They have always been an issue when it comes to product liability because you are obligated to give clear, complete, and reasonable instructions for installation, operation, maintenance, and repair. Negligence can also be found in personnel policies and procedures.

Campbell then goes on to the third type of violation, which is breach of contract. Policies and procedures are considered an implied contract even though they are not signed. The Michigan Supreme Court ruled that contractual obligations exists if the organization creates policies and procedures, then leads employees to believe that they are: established and official rules, fair rules, and rules that are consistently, uniformly applied to all employees. Implied contract claims frequently involve disciplinary or termination matters and are of special concern to personnel policies and procedures. Virtually anything you do or say that could be construed as a policy statement is under scrutiny.

Next, Campbell discusses the importance of disclaimers since users and courts may see your policies and procedures as an implied contract. She says that whatever type of wording you use for a disclaimer, be sure it’s strong, clear, and definite. For internal policies and procedures, a disclaimer should be added that declares that they do not constitute a contract and may be changed at any time. Campbell says that the disclaimer can be placed at the beginning of the handbook, as well as throughout the handbook. For external users, warranty disclaimers and other disclaimers are a means of clarifying responsibilities or consequences.

Then, Campbell discusses the need to update your policies and procedures. Courts expect you to keep people informed of your current standards and rules.

Campbell goes on to discuss the difference between manuals and handbooks. The term handbook may imply information that is widely distributed to a general audience, while the term manual may imply more detailed information that is restricted in circulation to a select audience and is considered confidential. Handbooks may create an implied contract, while manuals don’t necessarily create a contractual obligation to employees as a whole. The term user’s guide is used to avoid contractual obligations because the title implies that the book contains guidelines, not absolutes.

Next, Campbell discusses what the courts want the organizations to do to avoid legal risks. These include:
• Operating in safe, reasonable, fair manner.
• Communicating your policies and procedures clearly.
• Enforcing policies and procedures.

To conclude this chapter, Campbell discusses how to protect yourself. She says that there are no legal guarantees, but you should have the goals of reducing legal exposure and to be in a good position to defend yourself if it becomes necessary. You should focus on two factors: content that is appropriate, sufficient, and accurate and writing that is clear, understandable and precise. These factors fall into six categories:
• Word your policies and procedures carefully.
• Check the content.
• Reserve management’s right to discretionary action.
• Preserve your right to make changes.
• Consider the informal and unwritten rules.
• Use and enforce the rules.

Writing Software Documentation, Barker, Chapter 3

2007-09-17T12:39:00.000-05:00

This chapter covers what a procedure is, how procedures work, and what the writer should think about before writing a procedure.

The first item a writer should keep in mind is Relating tasks to meaningful workplace activities (64). Barker continues to say that procedures are parts of a whole and should be written with the clarity of how a procedure fits into the larger picture.

Determining how much information the user needs (66) is the second item on Barker's list. Detail in a procedure increases with the degree of difficultly of the procedure. A good rule of thumb is the more detail, the more visuals and explanations should be present. Barker outlines some different ways to enrich procedures:

Layering information for different users, those who already know part of the procedure and those who are learning for the first time.
Screen shots provide the users with a visual of what to do next.
Cautions & Warnings provide the user with advanced knowledge of how to retrieve information should it be lost.
Tips for efficient use help the user by offering an alternate method for accomplishing a task, or elaborating on a step or command.
Tables allow for efficient organization of information. A few uses for tables in procedures are to present information on features and uses as well as terms and definitions.
References to other sections of the manual or procedure or other resources
Explanations of any step or command

Choosing the appropriate procedural format (72) can have a major impact on how well received your procedure is. Four formats that are covered in this section.

Standard format which contains steps, notes, screen shots, and other elements left justified in one or two columns in a sequential order from first to last. Advantages of this format are its recognizability, its ease of flow from one page to another, the ability to easily re-number tasks, and the easy to see steps. Some disadvantages are the space it may require and the potential to be confusing if complex steps need to be mixed with simple steps.

Prose format puts steps in sentences and paragraph forms making it look and feel more conversational over Standard format's command approach. Advantages of prose are the relaxed tone, saves space, clarifies simple, basic steps, accommodates experienced users. Some disadvantages are steps buried in paragraphs, lengthy explanation of individual steps, inability to accommodate graphics, and the lack of support for novice users.

Parallel format shows a screen with the fields empty and parallels the field names in the steps that follow. This format is nice for programs with complicated data fields of dialog boxes. Some keys to parallel format are to keep terminology consistent, cue terms to the screen, discuss one screen at a time, use plenty of examples, explain the format to the user. Advantages of parallel format are the organizational benefits, great for complicated screens and dialog boxes. Disadvantages are it doesn't present the information in step by step format, it can not be used for all procedures, it may confuse users, it has to fit on one page.

Embedded help is the name for "interactive assistance" found in most programs today. Uses for embedded help are tips for effective use (reminders of keyboard shortcuts or suggested file names), cue cards (brief explanations of buttons and fields), short animated descriptions, and trouble-shooting tips. Different types of embedded help are:

Flyout help Help that appears in a box or panel on the screen at the user's request.
Interactive flyout help. This form monitors the user's progress in filling out a dialog box and highlights one step at a time until the procedure is complete.

Do it for me help this form of help contains links within the online help procedure that activate the screen element or dialog box described in the procedure.

Field-level help Help that provides information on how to enter information in fields.
Interface help. Help information (brief instructions) provided in a designated section of a screen.

Pop-up definitions Pop-up definitions provide brief definitions of interface elements activated by a mouse click.

Roll-overs Definitions of interface items that appear when you move a mouse over the item and (often) pauseFollowing a rhythm of exposition (80) means consistency through out the procedure. An example of rhythm of exposition is:

First I give command for the step.
Then I say how the program will respond.
Then I illustrate what happened.
Then I tell the next step.

Test all procedures for accuracy (81). Always conduct usability tests for your procedure to ensure that they are effective and correct.

The Discussion section (81) of this chapter begins with what constitutes a procedure. Procedures are used when a user is doing something with the program. Procedures function on the guidance level by telling the user which key to press next, what screens and reports will come up next, and how to get out of trouble. Procedures differ from the teaching level because procedures are geared towards what should be done at any given moment rather than a tutorial of the program. Procedures differ from support level reference documents in that procedures follow a chronological or sequential order.

Procedures work by maintaining a general layout of information. Each procedure should have a project-orientated name, i.e. Opening a file, or Recalling a Record from the Client Database. The task name is followed by an overview or introduction that orients the reader to the use of the procedure, reminding the user what the task will allow them to accomplish in a work setting. Following the overview are the steps. This aspect is the most important because it is the period of time that affects the user directly. Great care should be taken when writing the steps so the user does not get confused or lost. Methods you can take to try to ensure the user fully understands your procedure are placing smaller actions in prose format under the parent action or elaborating on a parent action, i.e.

Step 1. Choose Group from the Maintenance Menu.
Step 2. Choose an action from the Groups dialog box. Once you have opened the Groups dialog box, you need to select a name for the group, then select a directory name for the group, then set the access code to either Open or Restricted.
Step 3. Choose Close from the Groups dialog box.Elaborations help explain the steps as they are performed, which can help the user to avoid potential mistakes and perform procedures more efficiently.

Elaborations can also tell the user about alternative functions, toolbars, or keystrokes, how to tell if a step has been performed correctly, or where to look for additional information.Options or tables are suggested for use in procedures by organizing information and saving on space. These should be used when defining different keystrokes for the same operation, i.e.

To do this... Use these keys...

Set colors to black and white Ctrl-M
Revert to default colors Ctrl-D
Adjust the brightness Ctrl-B
Adjust the tones Ctrl-T

Screen shots, or screens, should be used when the user needs to see a tool in use or the results of an action. Screens are usually used for the following:

Give an overview of the main panel of an interface
Show the partial result of a procedure (a stage in the process) to help the user keep on track.
Show the final result of the procedure to let the user know where the procedure ends.
Show dialog boxes where the user has to make choices.
Show toolbars indicating which tools the user needs.
Show menus indicating what commands the user needs.

Feminist Theory and the Redefinition of Technical Communication

2007-09-16T16:56:00.000-05:00

Mary M. Lay

Mary M. Lay discusses the need for the redefinition of Technical Communication to involve a more feministic approach. Lay speaks of technical communication in the past as known for the affiliation with scientific research. As of the 1980’s and 1990’s technical communication has adapted ethnography and anthropological research methods. It has included them to involve within the workplace environment. This is when Lay develops her concern for feminist theory.
Lay is concerned with the matters of objectivism and ethnography in means of collaboration. Lay defines her theory with six categories that discuss feminist qualities and three categories that define debate among feminists.

Characteristics of feminist theory include:
1. Celebration of difference
2. Theory activating social change
3. Acknowledgment of scholar’s backgrounds and values
4. Inclusion of women’s experiences
5. Study of gaps and silences in traditional scholarship
6. New sources of knowledge – perhaps a benefit of the five characteristics above

Lay goes on to discuss the six points stating that women celebrate difference because they do not want to be defined in a general sense. That women value new knowledge and hope that leads to a better understanding. In terms of research women will place themselves on the same level as the subject of the research to better understand that subject. Women value their experiences as well as others and try to relate. Women will explore the unknown and criticize the original study or definitions. Five refers to the knowledge and information that women receive is compared to historical moments and past experiences, instead of an individual person or instance. Lastly, that self image is not just personal experience but is interpreted by others.

Lay goes on to discuss the three issues of debate among feminists:
1. Should feminists emphasize similarities or differences among men and women?
2. Should these differences be located in cultural or biological traits?
3. Should these first two issues promote or displace binary opposition?

The first debate talks about the differences or similarities among men and women. Lay talks about whether these characteristics should be accepted or if a state of androgyny should be erected.
Next she discusses whether these differences should be recognized as cultural or biological. She brings up the maximalist approach which is there are basic differences between the sexes and that they are essentially culturalistic. The minimalist position states that men and women are essentially similar and the gender differences are superficial and socially constructed.
The third issue is dealing with masculinity and femininity whether they should be separate and if so women are placed below men on a hierarchical scale.
Lay goes on to talk about objectivity, scientific method, and ethnography. Basically Lay is telling her audience that technical communication is formerly known as research and not only research but quantitative scientific method research that doesn’t leave much room for a subjective approach. Now that technical communication has evolved so should the definition. Women or more predominant in technical communication than before and ethnography is a more popular research method. Lay is trying to ask the question how is research methods presented by women going to change technical communication, in the sense that when women do research especially ethnography they will have different backgrounds and influences then that of men. Women are inherently more nurturing and concerned about feelings. In the matter of collaboration which Lay thinks will be the most effected, she discusses the potential conflict and difference between men and women and how the conflict would be resolved. Most importantly Lay questions whether these should be issues for technical communication and if so what kind of definition would be given to technical communication in the future.

Barker - Chapter 2 Summary

2007-09-11T01:54:00.000-05:00

Writing Software Documentation: A Task-Oriented Approach

Thomas T. Barker

Chapter 2 – Writing to Teach: Tutorials

This chapter focuses on the first of Barker’s three forms of software documentation: tutorials. Barker begins the chapter by explaining its objective, which is to offer “examples, guidelines, and discussion” for designing effective tutorials. He continues by describing tutorials as a form of documentation that involves focused lessons which guide a user through a process, assuming that their proficiency with the software will increase as they practice using it to complete tasks.

Barker divides the content of the chapter into two main sections, Guidelines and Discussion.

Guidelines

Barker presents a series of guidelines that are meant to provide a basic procedure by which one can create effective task-oriented tutorials.

Step 1 – Identify User Actions You Need to Support

Barker recommends performing a thorough user analysis to determine the actions and scenarios that would be most relevant to a particular use. Within an organization, it is possible that a single piece of software will be used in different ways by different employees. It is useful to identify and list program skills that a user will need to accomplish specific tasks. Some criteria that can help in selecting which program features to focus on include the degree to which those features are:

Central to job performance
Essential for efficient software use
Performed frequently

Another way of approaching this challenge is through an embedded tutorial (or EPSS) that detects when a user may need help on a particular topic and presents itself automatically at that time.

Step 2 – State Objectives as Real-World Performance

Tutorial writers, Barker asserts, should carefully define the learning objectives that they would like their users to achieve, and then state them for the user at the start of the lesson. These should inform the user, in measurable terms, what they will be doing in the tutorial and what skills the activity will impart to them.

Step 3 – Choose the Right Type of Tutorial

Barker describes several loose categories of tutorials, which serve different purposes depending upon the situation. The Guided Tour is an overview of program features that informs and persuades the user as to the usefulness of the program in a low-interaction environment. The Demonstration is a more focused presentation of a particular program function being performed, which tends to be passively viewed by users. The Quick Start is a form of documentation that is generally aimed at more advanced users and provides the basic information that one needs to dive into the program and interact with it on their own. A Guided Exploration guides a user through a procedure, but allows for some experimentation on their own. The most traditional form of tutorial is the Instruction Manual, which attempts to teach as much of the software as possible through a full series of interactive lessons.

Step 4 – Present Skills in a Logical, Cumulative Structure

A key component to effective tutorials is arranging the various lessons in a logical structure. This is often accomplished by organizing the lessons procedurally in accordance with typical workplace scenarios. Common cumulative structures include such progressions as beginning to advanced, generalized to specialized, and using default options to using customized options.

Step 5 – Offer Highly Specific Instruction

By soliciting very specific actions and information from their users, tutorials promote real-world skill building as well as confidence and interest in the program. Some examples of specific instructions include:

Specific data
Tools
Screens
Commands

Step 6 – Give Practice and Feedback at Each Skill Level

Barker recommends maintaining a highly positive tone throughout the tutorial, and praising users for their accomplishments whenever possible. He also advises building a pattern of exposition, by which the tutorial writer continuously:

Gives an action to take
Explains the results

Keeping lessons short (under an hour and ideally 10-12 minutes) will help make the tutorial more accessible to busy users. Including a convenient means by which one can pause a tutorial and return to it later is also beneficial.

Step 7 – Test Your Tutorial

Like any documentation, tutorials should undergo a thorough usability test. There are a variety of methods for doing so, but the most revealing information often comes from observation of an actual user making use of it in a realistic scenario.

Discussion

In this section, Barker explores the different elements that make up tutorials, and two philosophies of teaching that can inform tutorial design decisions.

Designing to Teach

Here, Barker offers some advice on how to decide when it is appropriate to use a tutorial versus some other form of documentation. Important considerations include the nature of the tutorial as a learning activity, and its narrow focus on achieving a very specific goal.

Selectivity in Choosing Material

In determining which procedures warrant tutorials, Barker asserts, one must rely on their user analysis. In doing so, a documentation writer will likely build tutorials based on the most common scenarios that their users will encounter.

The Elaborative vs. Minimalist Approach

Barker defines the elaborative approach as a theory of teaching that emphasizes comprehensive coverage of a topic, with the help of “summaries, explanations, examples, and articulations of goals and objectives”. Some research has shown that this approach can help users apply what they have learned to real-world situations more readily. This approach is consistent with Barker’s six principles of lesson design:

Instruction results in articulated skills.
Skills transfer capability to real-world performance.
Steps should present skills in a logical, cumulative structure.
Highly specific instructions work best.
Give practice and feedback at each skill level.
Master one skill before going on to the next.

Barker describes the minimalist approach as one that expects a certain impatience from documentation users, and attempts to serve them accordingly. He quotes John Carroll’s observations that documentation users often tend to:

Forego introductory or orienting documentation and dive right into interacting with the program
Skip information that does not appear immediately relevant
Resist restrictive instructional strategies and assert creative control over the learning process

Barker also references Carroll’s four principles adhered to by minimalist manuals:

Choose an action-oriented approach
Anchor the tool in the task domain (workplace context)
Support error recognition and recovery
Support reading to do, study, and locate

Ultimately, the decision to use an elaborative, minimalist, or hybrid approach depends on the situation and the professional judgment of the documentation author.

Barker concludes the chapter with a glossary of terms and a checklist for evaluating tutorials. He also includes a number of tutorial analysis exercises.

Campbell Chapter 2 - Where Do I Start?

2007-09-09T12:24:00.000-05:00

Campbell begins this chapter by discussing the importance of not skipping preliminary steps when trying to write an effective document.

Next, Campbell goes on to address the four steps to development, which is the preparation prior to drafting. The four steps are:
• Planning
• Analysis
• Research
• Prewriting
The time it takes to get through each of these steps depends on both the writer and the document. Campbell also notes that each step is needed in the correct order to make a successful document.

Campbell then begins her in-depth description of each of the steps, starting with planning. She says that a plan must be developed, and it is normally should be done in writing. The plan can be simple, but it should always be completed before any actual writing occurs.

The first part mentioned by Campbell is to set a schedule. She notes that schedules can be as simple as a piece of paper, or for more complicated projects, a Milestone or Gantt chart can be used. These charts show time frames for each step, and can also include personhours, assignees and overlapping steps. Campbell makes a point that schedules should not be skipped because without them, a deadline will surely be missed.

The next part of planning that Campbell discusses is using a team. She notes that because of the nature of some projects, a team works better than a single person. Team writing has both benefits and disadvantages like any team activity. Campbell says that success depends on good organization and clear communication.

Then, Campbell goes on to discuss being realistic, which is the last part of planning. She says you must again think about time frames, team members, possible conflicts and “brick walls,” and consider if they are realistic goals. Frustration is largely avoidable with realistic planning.

The next step in the four steps of development is analysis. Campbell describes analysis as a “realistic look at the audience, the assignment, the context in which it’s been made, how much and what types of research are required, and the conditions under which you’ll have to work.” She says to begin an analysis with the “what” and “why” of the project. Look at who is requesting the project, examine the reasons for the request and finally look at the nature of the project.

Campbell says that after the nature and reason for the request is known, one should be sure to understand the goal and the desired end result of the finished policy or procedure. If the goal of the project is not clear, this is the time to go back to the requestor for more information. Campbell states that you can’t help readers understand the importance of the policy or procedure if the writer doesn’t understand it.

Another part of analysis that Campbell notes is audience. She says that the more one knows about the audience, the better choices the writer can make in content, wording, format, and design of the document. The experience, education, preferences, expectations and attitude of the audience should all be considered.

Campbell then goes on to discuss the other elements to be analyzed when starting a project. She writes about conditions of document use, the urgency of the document, the impact the document will play on the organization and the project conditions. The analysis step is concluded by going back to the requested with updates. Campbell notes that writers have to sometimes fight for the resources to do the job, and these must be clear to the requester.

The third step to development is research. Campbell says that when this stage is reached, the writer is taking the first real action on matters of content. The amount of research is determined by the analysis of the project.

Campbell says that one should start with the most difficult, complex information, since it takes the longest to study and understand. She says to resist the urge to start with the easiest research first. Starting with the difficult research gives you time to ask questions, get clarification and resolve misunderstandings.

A writer should talk to content experts, but not stop there. Campbell suggests talking with anyone that holds information about the project. She says to talk to both internal and external people to gain insight about the project. To properly interview these people, the normal etiquette of informational interviews should be observed. One should have a list of prepared topics and questions, and the interviewee should be informed about the reasons of the interview. Campbell emphasizes the need to take notes. She says that a standard form of notes is good when interviewing a large number of people. These notes are the foundation of your document’s content, so Campbell says to take them carefully and accurately.

Campbell goes on to discuss soliciting information in writing, which is sometimes necessary if individual interviews aren’t feasible. She says to keep the solicitation as simple as possible and to remember that written requests are generally less effective.

Campbell then goes on to explain reading and studying. She says that when interviewing and surveying are not sufficient or possible, one should explore books, articles or trade publications that contain current, relevant material. Campbell suggests looking through organizational files, suggestion forms or comments during meetings, current policies and procedures, libraries and the Internet.

A final note Campbell makes about research is to concentrate on the critical information because a writer seldom has time to locate everything that’s out there on a given subject.

The final step Campbell discusses is prewriting, which is the missing link between the preparatory steps and the actual document. She says it organizes the material and speeds the drafting. Before drafting begins though, the material needs organized. A writer should have accurate and complete content, good organization, and logical flow before they start writing.

Campbell notes that a mind-map is a simple way to get all possible content concerns out on the table before the writing begins. She says the mind-map works better than starting with an outline because often content gets left out in a structured, numbered list. Mind-mapping eliminates the rigid list and lets the random, creative side thrive.

Campbell concludes this step and the chapter by stating that after the information that should be included is decided, it must be placed in the proper sequence. She says to create an outline of the mind-map by combining key words, phrases, sentences or paragraphs. The material should be put in a sequence or flow that’s logical to the reader, not necessarily the writer.