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.