Engl577Spring2008msumankato

Barker – Chapter 14: Designing Indexes

2008-04-14T12:32:00.000-07:00

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

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

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

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

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

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

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

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

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

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

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

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

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

2008-04-13T19:43:00.000-07:00

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

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

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

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

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

Production Courses

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

· Computer Applications Courses: hardware and software skills

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

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

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

· Introductory Writing Courses: introductory technical writing

Computer Literacy Classes

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

Courses Situating Technology in Historical, Political, and Social Contexts

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

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

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

Challenge #1: Balancing Technological with Literacy and Humanistic Concerns

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

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

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

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

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

Barker Chapter 12: Getting the Language Right

2008-04-12T12:58:00.000-07:00

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

Guidelines

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

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

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

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

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

Add operational overviews
Providing overviews cuts down on confusion for users who may not be completely familiar with the material. Tell them how the program benefits them. "Your manual is like a bathroom key: People want to get their hands on it not because of its intrinsic properties but because it lets them do what they need to do" (389). Writers primarily use three ways to emphasize explanations of abstract concepts: "the theoretical (emphasizing the theories behind the working of the program), the technical (emphasizing the technical functioning of the program), and the operational (empasizing the application of the program)" (389). Check Table 12.3 on page 390 for more details.

Discussion

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

How Do We Process Language?

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

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

Performance-Oriented Language

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

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

How Do We Remember and Learn

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

Structured Sentences

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

Style Problems in Software Documentation

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

Acronyms

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

Synonyms

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

Paragraphs and Sentences Too Long

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

Emphasizing the Computer Instead of the Program

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

No Connection Between the Heading and the Topic

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

Too Formal Tone

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

When to Use Humor

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

Ambiguous Task Names

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

Step Not a Step

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

Thanks! Team 3 (Carlson and Hood)

Barker, Chapter 13: Using Graphics Effectively

2008-04-11T06:49:00.000-07:00

Graphics are an important part of technical documentation.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

2008-04-04T14:42:00.000-07:00

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

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

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

What Means to Go On-Line: What Does Change

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

Advantages and Disadvantages of Going Online

Advantages (also see the table on pg 374)

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

Disadvantages (also see the table on pg 375)

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

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

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

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

Thanks! Team 2: Jennifer & Gary

Central Works Essay 31

2008-04-04T06:17:00.000-07:00

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

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

Definitions and Caveats

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

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

Cultural Differences in Behavior

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

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

Strategies for Internationalizing Collaborative Groups

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

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

2008-03-30T16:54:00.000-07:00

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

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

Situationally Embedded Text

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

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

Interactive Text

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

Functionally Mapped Text

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

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

Modular Text

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

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

Hierarchically Embedded Text

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

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

Navigable Text

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

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

Spacious Text

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

Graphically Rich Text

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

Customizable, Publishable Text

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

Conclusion

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

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

2008-03-28T16:17:00.000-07:00

Writers of policies and procedures will always face resistance and negative reactions to the finished product. Change can be difficult and can cause fear in employees. This chapter offers suggestions on how to lessen the resistance you undoubtedly will experience.

Campbell states, “The single most important thing you can do to combat negativity is to involve users upfront. Don’t end with involvement. Start with it.” One of the steps included in the original planning process was to talk to people and to get their input. Cooperation can be increased by involving people in the process from the beginning, even though it can be time-consuming. Even for those who still remain negative, by communicating with them early in the process, at least you will know who they are. “Forewarned is forearmed.”

As the writing process evolves, continue to gather input. Update potential users on the status, ask for opinions, and keep talking. Take the time to truly listen and to explain. Avoid portraying the message, “Trust us; we know best.” It will help to improve the final product and may also help to convert some of the resisters.

Final implementation will be less of a shock to users who have been included and educated throughout the process. For those who are unhappy, it is helpful listen to and acknowledge their feelings in a respectful way. Encourage questions. Let people vent. Enlist the help of those who are supportive of the changes. They can help to explain their positive reaction to those who are not happy. Some people will never be accepting of the change. It will be necessary to let them know that they are still expected to follow the change or to accept the consequences of non-compliance.

Grace periods can help to quell some resistance. The gradual transition period gives people time to adjust to the initial notice and allows them to ease in to the changes required. Reinforcing the message by repetition—in email, by posting it on a message board, by discussing it in staff meetings—will help to transition employees to the changes.

When the policy or procedure will be unpopular, “preempting” and “taking the heat” are two steps that will help you to deliver the bad news. “Preempting” involves anticipating objections and presenting them to the group before they have a chance to do so. By doing this, you can then follow up with a rebuttal response that addresses the objection and “steal(s) the objector’s thunder.” Patiently listening to objections and negative reactions, or “taking the heat,” can diffuse resistance as well by convincing users that you are willing to acknowledge negative reactions and to accept responsibility for them.

The chapter discusses common resistance factors towards policies and procedures and provides suggestions for dealing with them. For example, a policy might come across as being negative, unfair, pointless, or restrictive. It can be helpful to avoid negative words and to try to present things with a more positive spin. “Don’t take extended breaks” could also be written as “you must observe the scheduled break times.” Trying to see things from the users’ point of view, making sure that the organizations words and actions are consistent, and helping users to see how the policy might benefit them are ways to counteract some of the resistance factors.

And what if you strongly disagree with a policy or procedure that you have been asked to write? It can be valuable to acknowledge your own concerns, to even write them down. Then focus on the circumstances that are being addressed by the policy and the reasons behind them. Write these down as well. But ultimately, as a professional, you will need to abide by the policy, as others will. When writing the policy, give it your best effort and when implemented, help others to overcome their resistance.

When the process is over, take some time to review the policy or procedure. Is it working? Has anything changed? The process is not static, but is ongoing; things will eventually change, sooner, sometimes, rather than later.

(Team 5: Karen and Keeley)

Barker, Chapter 11, "Laying Out Pages and Screens"

2008-03-28T11:26:00.000-07:00

Document layouts basically fall into two kinds of activities: designing page layout and designing type.

Designing page layout is determining the best arrangement of words and images on a page or screen to achieve maximum usability.

Designing type is determining the proper font, size, and style of characters as well as determining the format for tables, lists, and paragraphs.

Constraints compare the design process: constraints of user types and experience, of the user’s problem-solving techniques, and of the documenter’s resources. Account for these constraints in any intelligent design of page and screen layout to achieve the design goals.

The Goals of Page and Screen Layout
The goals of layout are to allow the user to overcome the design problem. First, the layout should meet the dynamic needs with a static document. The document should support task orientation by helping the user perform information-related tasks efficiently and productively. Secondly, good page and screen layout should support overall task orientation. Finally, the layout should accommodate the visual needs of the user, the need to learn, and do it through images rather than words.

Create Page Grids
The user analysis creates a kind of model, telling the characteristics of the users in a way that allows you to design documents to help the user perform meaningful, automated work. The model of your page design first emerges as a page grid. Page grids define communication space by drawing invisible “fences” around the areas of a page. A page grid acts like a scaffold onto which you put text and graphics.

To design a page well, you need to know the following about grid lines and the other parts of a page grid:
• Grid lines: Lines drawn where the page and column margins would fall.
• Margins: Areas of actual space between the text and paper’s edge.
• Columns: Spaces between the grid lines marking columns.
• Gutters: Space between columns.
• White space: Space, inside the margins, where no text or pictures may go.
• Baseline: Grid line at the bottom of the text and graphics area that defines the bottom margin.

Define the Page Grid Using Styles
When you have identified a grid for your pages and screens, you’ve identified the basic pattern you will follow throughout your manuals and online help systems. Some pages will look different from the grid pages (e.g., table of contents and indexes). Once you’ve decided on the grid for your pages, you should identify the styles you want to use to set up the pages. Table 11.1 on page 355 of Barker shows many different rules of styles for page and screen components.

Two important things to note about the guidelines are that the screen presentations don’t identify margins in a one-column format because the margins are automatically set by the variable-sized window in which the help screen appears. Also, the font for the body text is a serif font for printed documentation and a non-serif font for screen presentation because serif is more easily read on a screen.

Draw Thumbnail Sketches
Use a thumbnail sketch as part of your planning effort for your publications department or to experiment with different plans for the style manual. Barker suggests picking a page that you think exhibits good page design. Barker then lists an exercise beginning on page 356 to sketch out an example page and compare them.

Barker also lists the following guidelines for sketching the thumbnail:
• Text: Draw straight lines for all body text lines. Use a ruler, or learn to draw sketch-straight lines (where you put your pencil at a starting point and draw short, straight strokes to the ending point).
• Graphics: Draw all the graphics using shadows, abstract sketches, and circles and lines.
• Headings: Headings usually appear in larger fonts than body text, so draw them as shaded rectangles, again using their relative size in the original as your guide.
• Rules, boxes, other features: You may need to draw rectangles around rules to give them the same value on your sketch as they have on the page. Make sure to include all the graphics and text in the headers and footers.

Tips for Drawing Thumbnail Sketches
1. Drawing a thumbnail sketch may take 10-20 minutes. Take your time and make it accurate.
2. Keep the page items in proportion while trying to include everything that is in the original.
3. Keep the values of darkness, density, lightness, and spaciousness the same in your sketch as in the original.

Set Up Pages and Styles in Your Word Processor
Once you have identified your styles, set them up in your word processor or desktop publishing program. You handle the specifications for page in two ways: styles for the text and page setup. Depending on what you use, you could do these together or separately.

Setting styles saves you time for two reasons:
• You can change the styles later, and you don’t have to change each instance of a certain text.
• Setting up styles ensures consistency.

Determine the Layout of Help Documents
The number of fonts that work on screen is different than the number of fonts that work on paper. There are many different elements to consider when selecting layout elements. See Table 11.2 on page 360 for a list of layout elements for page and screen consideration.

Discussion
Designing Communication Spaces
The documenter needs to decide two important things: the degree of modularity pages need, and the degree of structure they need. These two elements are what determines the overall look of the communication space, regardless of the pattern of columns and words you chose.

Degree of Modularity
Modularity means breaking information into chunks of text and graphic units and fitting them onto a one- or two-page spread. Using this format, you would use the one-task-per-page idea, and include at least one image per task.

Modularity and Pages
Ask yourself if the communication space contains all the information the user needs to perform the task and understand the concepts in the task to determining the degree of modularity for a page or screen. Keeping tasks self-contained increase modularity. Follow these steps to ensure modularity:
• Repeat background information where necessary.
• Repeat screens when necessary.
• Include orienting information about the relationship of a task to other tasks.
• Keep all relevant steps on the same page.
• Minimize cross-references.

Modularity and Screens
Note that modularity has less and less to do with online help systems. Because of the physical restraints of a page, you have to put all the necessary information in one space. Use expandable text and rollovers to assist in getting the important information to your users.

Degree of Structure
Structure in page design means that we place the information on the page according to patterns, with certain kinds of information only in certain places. This process reserves certin areas of the page or screen for certain kinds of information. The structured page has areas for headings, certain areas for overviews, and others for screens. Highly structured pages use bulleted lists, tables of commands, and indented margins for steps.

Elements to consider when looking at a structured approach:
• Rules: Various lengths and thicknesses help the user tell the reading area from the heading or scanning area.
• White space: Helps the user focus on elements of the page such as graphics without having to process impinging information.
• Bullets: Help the user identify the kind and organization of information at a glance.
• Chunks: Help the user identify reading information in overviews and elaborations.

How to Look at Pages and Screens
Try to develop an eye for the following elements of page design:
• Page density: Comparing the pages of one manual to another.
• Balance: Compare how one manual balances white space and text space with one another.
• Legibility: Compare the ease of reading of the type font and style among manuals which you think read clearly.

Common Page Designs
Many designs used in software manuals incorporate the concepts of modularity and structure to varying degrees. There are two common formats that are used, the two-column and the one-column.

Two-Column Format
Most of today’s software manuals display a two-column format (example on page 366). This format allows the reader to distinguish readily between guidance information and support information. The two-column format works best with guidance-level documentation: procedures, step-by-step, installation, getting started. The two-column format uses more space per information unit than dense one-column format.

One-Column Format
The one-column formatted page (example on page 368) arranges both graphics and text in the middle of the page. In some ways, the one-column format helps a writer modularize a document because it makes it easy to keep task information together in a linear form. Writers have used the one-column, full-page format for tutorials, which tend to have longer passages of prose, because they think it is easier to cram a lot of information on one page. This, unfortunately, leads to this page not being read because there is too much information on the page and readers skip over it.

The Elements of Page Design
Pages consist of the arrangement of many complex elements. By understanding the following elements, you will understand the building blocks of pages.

The Left Margin
Text and graphics align according to the left margin.

Columns
Columns can be easily created using many different kinds of software. There are two kinds of columns, newspaper and table. Newspaper columns continue text from the bottom of one column to the top of the next column on the same page. Table columns continue text from the bottom of one column to the top of the the same column on the next page. This is the best column format for manuals, particularly when one column contains graphics and the other text.

Headers and Footers
Headers and footers orients users through sections, pages, and topics without taking up a lot of space. Consider users' needs when selecting header and footer styles and content.

Icons and Diagrams
Icons, diagrams, and pictures are some of the visual elements that make paper or online texts easier to use. They help users to easily locate critical information or to navigate different sections. A well-designed page uses ample icons and diagrams that are emphasized with appropriate white space.

Screen Shots
Screen shots provide users with useful visual references. There are three kinds: full screen, partial screen (emphasizing only part of a screen), and menus. Selecting the appropriate size and labels is important for designing a useful screen shot.

Rules
Rules help designers line up columns, emphasize sections of information, and define headers and footers. They vary in width, length, thickness, tone, color, and style depending upon users' needs.

Pagination
There are two kinds of pagination: sequential and modular. Sequential pagination uses the same sequence of numbers from the beginning to the end of the entire manual. This is especially useful when users refer to a series of books, such as a supervisor's guide and a user's guide. Modular pagination involves starting each chapter in the same book with page one. This may be useful for guides that contain distinct contents in different chapters so that individual chapters can be reprinted while maintaining pagination. Whatever pagination is used, designers must ensure that pagination for special sections, such as the header, or special chapters, such as the index, helps orient the user.

Common Screen Design

Windows Screen Format
This format includes a non-scrolling section and a one-column design with links to related topics (or two-column design that places the related topics on the right). Designers can also add links that open pop-up windows to explain functions.

Man(ual) Pages Format
Man pages format is simpler, containing a heading, a title at the top, and a navigation area with a prompt.

The Elements of Screen Design

A Changeable Space
Designing screens can be a challenge because users can change how content is viewed. Because users can resize and scroll through screens, designers should keep several things in mind. Forget line length: only left and indent margins usually need to be configured because users can resize screens. Avoid lots of scrolling: shorten text length to no more than two screens or users may lose their place. Indicate the extent of the topic: if text continues from one screen to another, use a "More" button or pagination to help orient users.

Multiple Window Management
If designers include help windows in their design, they should follow several guidelines. Don't obliterate the users's work: configure the help window to cover only part of the screen so user's can still find the original window. Avoid window clutter: minimize the number of help windows that open or place help windows above the application window so it is easy to refer to. Give the user control over frames: make it obvious to users whether help windows will close automatically with a click or keystroke, or whether windows will close automatically after a set amount of time.

Color
Designers should use appropriate color to highlight important sections, information, or tools.

Graphics
Graphics should be simple for easy on-screen viewing and printing.

Screen Grids
Grids on computer screens different from grids on paper in several ways. Narrower margins are used on computer screens because the monitor helps define the viewing space. Less indentation is needed on screen to save space and because fonts are usually larger on screen. Define the grid for single pages only: binding and two-page layouts aren't a concern with computer screens. Use rules sparingly: topics tend to be better defined, so rules are less necessary.

Line Spacing
In general, single space lines and use large font size in headings.

Designing Type
Designers should understand the tools available (such as software) and the way users recognize words to design the appropriate type for manuals.

Helping People Recognize Words
Besides users' technical proficiency and subject knowledge, it's important to understand that users are visually oriented. This means that the shape of words and the letters they contain can influence readability. Serif fonts have letters with end strokes that almost connect to the letters that follow, while sans serif fonts don't have those connectors. Serif fonts look more like cursive writing while sans serif fonts look more like printed writing. Serifs can encourage eye movement across the page, especially with smaller letter sizes.

Design Advice
Choose a font the user knows well for the body text.
With smaller-sized type, choose font styles with well-defined ascenders and descenders.
Avoid using italics or all caps for long strings of text because letters can be harder to distinguish and understand.
Keep heading short.
Use serif for body text (where comprehension is most important) and sans serif for headings (where larger sizes make comprehension easier).

Building Patterns with Type
Create a consistent pattern using cuing techniques, headings, and rules when designing manuals. This helps users locate important information and navigate through sections more easily.

More Design Advice
If designers want to change fonts, sizes, styles, they should do it in this order: style, size, then font. Change only what is necessary to emphasize the text. Limit the levels of information to two (three at the most) so if you need to make changes, you'll have to do it fewer times. Limit cuing devices to three or four for a cleaner look. Use a consistent design in the manual and related documents. Use software to establish a consistent paragraph style that will carry throughout the document.

The Idea of Body Text
The body text is the dominant feature of the document, and size and style can be varied, but not font. The most common body text fonts are 10- or 12-point serif. Still, it is important to consider the page size (which should correspond to the font size), media (screens may limit the font options or some programs may offer special fonts), and user expectations (such as what may be viewed in other manuals).

Non-Body Text
Body text can be modified in style, font, or size to create headings, warnings, or notes.

Headings
Headings should direct users to important information through special spacing or size. Heading design, however, should be consistent across levels. Headings should generally be larger, sans serif, and bold for emphasis. Alternately, headings can be differentiated using small, medium, and large sizes of the same font.

Hints, Notes, and Cautions
Hints, notes, and cautions are special "aides" that draw the user's eye through color, icons, and spacing. Because they are generally included in the body, they are the same style, size, and font as the body text. However, they can be emphasized by changing the size or style of the heading preceding the information.

User Input, Computer Output
When it is necessary for users to type in text and for that text to be displayed, this text usually appears different from the body text. Courier has been commonly used for input because it looks like typewriter text, which may serve as a prompt to users. For output, Helvetica is a common font because it may look like the body text but is still distinguishable by its smaller size.

Tables and Lists
While the text of tables and lists is generally the same as body text, the heading styles may be changed for emphasis. Other ways to distinguish tables and lists are indentation, column layout, and rules.

See pages 380 to 381 for the Glossary and Checklist.

Submitted by Team 1

Summary of Chapter 11: We Haven’t Used that Procedure in Years

2008-03-24T06:39:00.000-07:00

This chapter is devoted to answer the questions that arise when procedures need to be revised. Companies are expected (and legally held accountable) to keep their organizational records up-to-date; specifically, when a company holds ISO 9000 standard certification, it is a requirement to have all policies, procedures and manuals up-to-date and to have only the active copy “active” i.e. being used.

Additionally, the unusable state of a procedure makes it useless and redundant as well as obsolete. Usually, the writer can receive best feedback about the use of a procedure from the end-user. The writer should also keep in mind that policies and procedures require a regular update and maintenance to remain usable and accurate.

When should a procedure be revised?
According to Campbell, there are two methods:
1. Regular review and revision
2. As-needed review and revision

A company should evaluate, which method would be more appropriate and beneficial. Often, ISO certifications require a regularly scheduled review and revision, but this can be difficult for companies that have limited resources and overwhelming if all documentation is updated all at once. A solution to this can be a rolling review that staggers documents in groups. As-needed reviews are risky, because they are more vulnerable to procrastination and justification: after all, how can you measure need? Campbell provides some pointers on how to implement as-needed reviews: the company can revise a procedure after accumulated changes, significant content changes or after observing some clues (such as: complaints, questions, errors etc.) that reveal the procedure’s complacency.

Of course, there are times when a revision is not required; before rushing into the next revision, the company should evaluate whether there are other factors that contribute to the lack of following a procedure. This could be lack of training or lack of management support to enforce that process, or people may simply take time to accept change.

Once the decision has been made that the procedure needs to be revised, there are several factors to consider:
· How much should be revised? Revision Content
· How should the writer revise? Revision Process
· How to communicate and clarify the changes? Revision Awareness

The revised content can be communicated by highlighting the added/revised content, using clear wording in the transmittal document and finally, summarizing the changes that were made. This is also important when maintaining ISO certification.

After the document has been revised and all changes are highlighted and summarized, the revised procedure can be published. In order to ensure that all users take responsibility in application of all changes, a system should be in place that prevents user excuses, such as “I never knew about these changes.” A simple sign-off roster/revision index/action memo for all employees works well. That way, each user can be held accountable for having read the changes and knowing about them.

Finally, Campbell provides some helpful templates and tip sheets in the Appendix for Chapter 11.

Thanks for reading our summary: Lance and Vanda

Barker Chapter 10: Designing for Task Orientation

2008-03-22T18:27:00.000-07:00

This chapter presents tools and techniques for responding to characteristics of software users.

Guidelines for designing documentation

Create a table of contents

Match the user analysis with information design strategies

Acknowledge production constraints in document design

Test and review the design

Follow a design process for online help

1. Create a Table of Contents

Think in the sequence of stages that begin with goals and end with solutions. The prior user analysis with suggest overall goals. The outline embodies your most innovative and user oriented ideas. Decide on the overall organization of the manual and how to design so the user can easily find information.

Match the user analysis with information design strategies

When designing for different groups consider the following:

· Navigational aids- Navigational aids make sure the user groups get to the information pertinent to their needs. These could include special statements, directing users to the sections of the documents, list of figures and tables, headers and footers.

· Scenarios- Scenarios give each group a role model.

· Icons- Icons identify information for each group.

· Metaphors-Metaphors make implicit relationships to the workplace so users can see and feel the document is familiar to them.

Design for a specific program issues:

· Job performance aids cover technically or repetitive tasks.

· Background information to meet special needs.

· Special forms can help users collect information in the field for later inclusion in the document.

Meet the user’s task needs

Illustrations, layout design, examples of usage, special document sections, and tips.

Meet the user’s information needs:

This requires you to understand how users manage information within a job setting. There are several strategies you can use:

· Explanation so the user understands their use and importance.

· Provide examples that illustrate workplace uses.

· Meet efficiency goals/command summaries for efficiency by providing things like shortcuts, macros, etc.

· Identify functions that relate to information management and communication work

Match the user’s computer experience –

There are different types of users like: novice, experienced, and expert.

Enhance the user’s subject-matter background:

Take advantage of the user’s knowledge of the subjects by doing the following:

· Special glossary of background terms

· Index entries linking background terminology to program functions

· Special booklets/sections describing background concepts

· Elaborate examples with explanations of key concepts

Leverage the user’s workplace

Try to incorporate the following to help new users:

Getting help from coworkers

Suggestions for support groups

Descriptions of network use

Meet the user’s learning preferences

Learning preferences are connected to the choice of media as well as design.

Instructor learning – For instructors use lesson plans, overheads, etc. For the learners use workbook, note pages, diskette.

Manual learning – Tutorial manual, list of learning objectives, samples files

Computer-based learning – Programmed computer-based training modules, etc.

Meet the user’s usage pattern

First determine which category is most appropriate: Regular usage, or Intermittent usage, or Casual usage.

Acknowledge production constraints in document design

Decide on what design features you would like to have and what you can afford to have. You need to know you limitations before planning. Some constraints are: Writing tools, Production tools, Human resources, Budget, and External considerations. See table 10.3 for further explanation of the constraints.

Test and review the design

In this phase you evaluate through reviews by clients and sponsors and test problematic areas in a lab or field test. To test your design you can follow these steps:

a. Mock up pages with access elements on them and field test them.

b. Consult the chapter on testing for was to do quick usability tests.

c. Decide on a design based on logic and experimentation.

Follow a design process for online help

The design of online help should parallel the process of designing for print; however the process must be adjusted to accommodate: technical differences between print documentation and online documentation, and the different features of online document versus pages.

Identify and list the online help topics

Topic is an identifiable body of usable information associated with a user activity.

The 7setps program identifies the following kinds of topics.

About – offers introductory information of the program

Module – describes the modules of an interface

Action – describes situation in which a user would use a part of the interface to achieve a workplace end

Problem – describes solutions to problems/bugs/errors

Questions – describe questions the user might ask

Task – identifies the workplace activities the program supports

Update – describe new features of a program or application to the users

User group – describe the types of users with similar ways of using the program.

The two types of automatic topics are:

“Best practices” – when the user has performed an operation that is potentially complicated and would need more guidance

Corrective – topics open when a user has reached a dead end

Determine the interconnected elements

Those interconnections among topics based on user activities make up the heart of a help system because they allow the users to follow familiar patters of activity.

Decide what design features to use

Design features are the software capabilities you can build into a help system and the electronic interface elements of a help system. Some features of the help systems are: Hypertext links, buttons, hot areas, browse controller, pop-ups, context sensitivity, and system affordances. See table 10.4 for detailed description of each.

Here are several areas to consider when designing for task orientation:

Accommodating groups of users

You must constantly consider the degrees of experience among the groups of users. You may have to write more than one manual to accommodate the different needs and expectations of the users.

Pay attention to users psychological differences as experienced users may have more patience and confidence with the program .Novices have less experience with manuals and online help and do not know the conventions of documentation thus can get lost looking for things in the wrong section. As a documents designer use a variety of features (glossaries, cuing, graphics etc) to help novices and get them on track.

Consider the roles based on computer experience and professional activities such as installers, operators, evaluators, decision makers and so on. Each of categories of users needs to use different functions of the program and need different level of support. Writer needs to use different cuing to make sure each user’s type can find appropriate section easily.

Matching the user’s problem-solving methods

There are several issues to consider:

No one carefully reads more then 2 sentences at a time.

Solution: Make paragraphs short. Include tables and lists whenever possible.

Most users begin using the table of contents before they ready the manual.

Solution: Make table of contents complete. Use abbreviated, complete and chapter-by-chapter table of contents.

Most users go to the manual or help only after they have failed to perform tasks.

Solution: Describe error recovery clearly and completely.

Most readers do not read instruction first.

Solution: Replace introduction with information about users needs, special documents features, or helpful routing information.

Most readers do not read any sections in its entirety.

Solution: Tell users which section to go for particular tasks/problems. Make sure all descriptions of tasks are complete for performing task. Repeat important information.

The Design Guide for Printed Documentation

Navigation

Navigational aids are elements of a document that tell the reader where to go next for what kind of information. Make sure you include navigating as organizing feature only after you have examined your user’s tasks carefully.

Cross-reference points to other sections of the chapters containing related information. Try to include the cross references and information that the users need at the point they need it.

Running header and footers - This may include: chapter and section names and numbers, book title, graphic cues and icons, task names, and color to indicate sections.

Layering – refers to having two versions of information on the page at once to satisfy more then one type of reader. Things like keyboard shortcuts on the side, use of columns for instructions, etc. You might have elaborate steps for novice user and abbreviated version of the steps for the experienced user.

Headings – All manual use heading, and all users expect them. Use short phrases to indicate contents of the section such as “Setting Margins” or “Saving a file”. Avoid making headings too short- “Margins”/”Save”. Headings also create visual part of the pages.

Advance organizers – tell the users the structure and organization of the information that will follow. Remember to put advance organizers in front of the information they reflect, use them consistently, make sure they relate to user’s work/tasks, and keep them short.

Document overview – Users need to be introduced to document’s setup and how to use it to find information. You can include things like: audience, content, organization, scope, and navigational information.

Parallel structures – There are two benefits of parallelism in software manuals. First parallelism reassures the user that the writer has sorted out the important information. Second, it creates pattern of expectations so the reader learns how to use the document.

Cuing – This refers to the technique of including visual patterns to make a certain kind of information memorable. You can cue with icons or rules, fonts, and caps.

Indexing and tables of contents – The two most important navigational and tracking devices in any manual. The table of contents describes the content of the document from a task perspective. The index provides a meeting place of all users of a program.

List of figures and tables – They make up the main element in the usability of a document and help users see quickly if they can find an example of a screen in a figure.

List of screens – This list works when you have program with easily recognizable screens. This list of screens should appear early in the manual or in the primary index screen of a help system.

Interrelated examples – These are examples when you follow the same example from one procedure to another. Doing so builds continuity into you document design.

Solutions to the design problem for online documentation

Here you face the same objectives as you do with the print document which is getting the user the right information.

Non-scrolling regions – regions that appear at the top of the screen and stay there while the user scrolls through the procedure or topic. This feature has advantage over the print document because user does not loose sight of the document.

Expanded text – Sometimes called “stretch text” allows you to embed more details into a topic so the user can click on the expanded text link to view details.

Keyword and whole text search – refer to the ability of a help system to electronically find topics and the user types into a keyword search box.

Indexes – shows an alphabetical view of all the important topics and terminology used in a help system. The author has to identify some terms for index to ignore when presenting the list to the user.

Links and Jumps – in a help system allow users to go directly from one topic to related topic. Here online system has definite advantage because user does not have to turn pages and can link topics and get back and forth between topics.

Pop-ups – provide a way to handle glossaries in an online system. User can click on the term in the topic window to see the definition.

Context sensitivity – With a print manual, the user goes through a chain of events between identifying a problem and finding the solution. With the online help system, user goes directly from a problem with a screen or a field to an appropriate help topic containing a solution. However the limitation is that you can’t guarantee that the user will get right information.

Histories – allow the users to trace their steps, save histories and refer back to them. This is advantage over using print material.

Browse Sequences – When you identify a series of related topics you cab easily include the relationship in the form of browse sequence. The system displays forward and backward arrows when moving from topic to topic using browse sequence which cannot be done as easily with the print material

Bookmarks/Annotation – With a book the user can easily mark a place in the book and then return to it as well as mark on the pages. Newer help systems also have incorporated bookmark options as well as annotation features.

The Politics of the Interface: Power and its Exercise in Electronic Contact Zones

2008-03-21T19:59:00.000-07:00

We need to be technology critics as well as technology users…

Selfe, C.L., & Selfe, R.J. (1994). The politics of the interface: Power and its exercise in electronic contact zones. College Composition and Communication, 45(4), 480-504.

The borders of social power are so commonplace in society that they often remain invisible. Selfe and Selfe explore computer interfaces as a border that represents dominant tendencies in American culture, proposing that consumers should not only be technology users but also technology critics. They wrote this article in order to identify some of the effects of domination and colonialism associated with computer use to “establish a new discursive territory within which to understand the relationships between technology and education” (p. 482).

Computers have been used in the hopes to democratize the classroom and may be less systematically oppressive. However, this is a dangerous assumption—the belief that computers and networks are “the same for all players.” Rather, Selfe and Selfe evaluate and present that computer interfaces value “monoculturalism, capitalism, and phallologic thinking” (p. 486). Interfaces include icons orientated to the ideals of the white, male, middle- and upper-class professional (i.e. white pointer hand). English is also the default language of interfaces and many commercial items only come in English.

These primary interfaces do not provide evidence of different cultures, races, linguistic groups, or economic statuses. Interfaces exclude and marginalize Other perspectives, and in doing so, enact a gesture of colonialism. Interfaces, therefore, operate as a grand narrative where users must abandon their “own culture or gender to acknowledge the dominance of other groups” (p. 494).

The authors propose that users need to recognize these cultural and linguistic borders to reveal power differentials. Interfaces must also be revised to reflect a range of cultural, linguistic, and ideological perspectives to represent the “underrepresented”—non-white cultures, non-English speakers, and women. Users cannot be mere objective observers of these barriers.

Overall, Selfe and Selfe illustrate the computer as a gendered, classed, and racist technology in this critical essay.

Group #2: Jennifer and Gary

Essay 27 - Who "Owns" Electronic Texts?

2008-03-21T14:49:00.000-07:00

Who “Owns” Electronic Texts? By Tharon W. Howard

In 1996, if you violated someone’s copyright you could be sued in civil court. Today, because of the “Digital Millennium Copyright Act of 1998” you may face up to a $500,000 fine or five years’ imprisonment for your first offense. Sonny Bono’s “Copyright Term Extension Act” in 1998 extended the length of an author’s copyright another twenty years and copyright is granted for seventy years after the death of an author and, in the case of “works for hire,” ninety-five years from publication or 120 years from creation.

Today, corporations like Disney, MGM, and A&M Records can force the public to pay for images of Mickey Mouse, video clips of King Kong, songs like “Happy Birthday,” and other cultural icons for up to 120 years. Remember the lawsuit against Napster in 2000? Lawsuits are continuing to define the limits of the peer-to-peer technologies and copyright laws.

Most writers, including practicing professionals and teachers don’t consider the issue of intellectual property as particularly problematic. Writers today do expect some sort of remuneration for their writing and control over how their texts will be used.

Recent trends toward more collaborative writing projects in the workplace, along with the use of online computer conferences, electronic discussion groups, hypertexts, multimedia presentations, groupware, and other computer technologies aimed at enhancing and promoting collaboration, are all seriously challenging the popular, romantic view that an author owns his or her text. With an increase of reliance of computers in the workplace, writers are finding themselves confronted with intellectual property and copyright issues.
Five scenarios were given with questions about workplace issues.

Scenario 1
While working for a large corporation in the document design department, which prides itself with producing dramatic covers for the company’s annual reports, your co-worker finds a photo that would be perfect for the cover. With a little cutting, pasting and a few other modifications the photo will work. The photo is famous and since only part of the photo is going to be used and the image will be modified and essentially new should you go ahead and scan it? Or do you first have to have permission from the magazine which first reproduced it, the publishing house which sells reproductions of it, or the photographer who originally took the photograph?

Scenario 2
You’ve just been hired by a desktop publishing company and have received a new computer with software that isn’t compatible with other employees’ software. Your boss tells to load your computer with the old software that the office has because they have already purchased the disks. Should you go ahead and copy the software since the office has already paid for it?

Scenario 3
You’re doing research on an article about usability testing for Technical Communication and, as part of your research you join an online discussion group where others are doing human-factors research exchange e-mail messages about their works-in-progress. Someone posts an e-mail that changes your way of thinking about your own thesis. These are unpublished results and you want to quote from the e-mail message in your article.

Can you legally and ethically quote from an e-mail message? Are you obligated to cite the message since it has had such a profound impact on your own thinking? If so, does anyone own the copyright on the message? Do you need to seek the author’s permission? Or, since the message was electronically published by an electronic discussion group, do you need to have the permission of the person(s) who created and operate the discussion group or the university or company which owns the computer that hosts the group?

Scenario 4
You work for a large corporation that uses e-mail throughout the company in lieu of paper correspondence. You have been keeping correspondence with another co-worker, who happens to be of the opposite sex, and keep this correspondence to breaks and lunch periods so that it does not interfere with business hours. Your supervisor is aware of this and agrees with the situation. However, you have found out that your e-mails have been monitored and the butt of jokes. You are furious and you report this to your supervisor. Your supervisor tells you that the company owns the computers and therefore, has the right to monitor their use.

Can you stop this monitoring of your e-mail? Who actually owns the messages you’ve been sending? Do you, as the author, own the messages? Does the addressee who received them? Or does the owner of the system on which the messages were produced? What rights does ownership of the messages entail?

Scenario 5
You are a placement director at a large university in the professional writing program. To help graduates find information about companies that hire writer you set up a HyperCard stack which allows students to click on a state on the U.S. map. This stack is located on computers at the university and from a book which provides an alphabetical list of national corporation, you select data on companies which you think might routinely hire technical writers. The hypertext is so popular that several publishers learn about it and want to publish it.

Can you publish your hypertext? Have you infringed on any copyrights by providing your students with your hypertext in the first place? If you can publish your text, are you legally obligated to pay any royalties to your university or to the publisher or author of the book from which you selected your data?

To understand the problems of ownership in the electronic workplace Howard offers a brief historical examination of the origins of U.S. copyright law. He explores why electronic publishing, electronic discussion groups, computer conferences, and other new information technologies represent such a challenge to current copyright law. A historical examination of the printing press will show that then, as now, the introduction of new technologies challenged existing systems for owning and controlling texts. The examination will show current copyright law reflects an interesting struggle among at least three historically distinct and competing theories of textual ownership. First, of course, the romantic and commonplace notion that authors have a “natural right” to the fruits of their intellectual labors. Second, there is the assertion that the public has a right to all knowledge since “Laws of Nature” and absolute truths cannot be the property of any one individual. And third, there is the view that all knowledge is socially constructed, that a text is a product of the community the writer inhabits, and that the text must therefore be communal, rather than individual, property.

A Historical Overview
Copyright can be defined as the “right to reproduce copies of a particular text” (400). It was not and still is not a “natural unlimited property right” (Beard). It is a limited privilege granted by the state, in that the government gives writers the license to “operate” texts in the public domain.

In the 15th and 16th centuries, before the invention of the printing press, the creation of books depended on the patronage of the Church or the Crown, who then were able to control the kinds of texts both produced and consumed. The printing press led to a radical reduction in production costs, but the limited number of popular and lucrative texts available for publication increased competition. This led to the creation of the Stationers’ Company, which was a voluntarily enforced form of copyright. Thus, the Church and Crown lost their control over the production and consumption of texts, which in turn led to the creation of “subversive” texts.

In 1566 Mary Tudor and Philip of Spain granted the Stationers a royal charter, and it became a firmly established principle that a copyright is not the natural, unlimited, or absolute property of any individual or company. It made it clear that to own a copyright is essentially to own limited license or privilege granted by the state to promote intellectual activities deemed by the government to be in the best interest of the state and its citizens.

In 1709 Parliament’s Statute of Anne provided the basis for Article I, Section 8 of the Constitution, which recognizes the rights of authors.
Major Principles of U.S. Copyright Law “Copyright law in the U.S. recognizes that in order to encourage authors to produce the texts which will lead to the artistic, scientific, and technological discoveries that drive business and industry, it is essential that authors be allowed to realize a profit from their texts” (402). Copyright law does not give authors and publishers the legal right to prevent the public from “fair use” of texts, according to Statute 17, Section 107 of the U.S. Code. It grants the public a right to copy a work “for purposes such as criticism, comment, news reporting, teaching (including multiple copies for classroom use), scholarship, or research” (402).
Factors to be considered to determine if the use of a work is fair include:
• The purpose and character of the use (is it of a commercial nature or for nonprofit educational purposes?)
• The nature of the copyrighted work
• The portion used in relation to the whole work, both in amount and substantiality
• The effect of the use upon the potential market for or value of the work (17 U.S. Code, Sec. 107) (403)
Only the tangible expression of ideas belongs to the copyright holder, not the ideas themselves.
Copyrights in the Electronic Environment

Actual legal status of textual ownership does not match commonly held beliefs about
the copyright and “who own what” question. Authors own the text rights after text is produced and they are protected by copyright law with limited privileges granted by the State.

The professional communication fields in general and technical writers in particular need to understand the general principles of current copyright law. In addition it’s important to realize that some copyright principles do not always apply to electronic texts. Many professional writers are aware of “fair use” principle, and protection of form of expression but are unsure about copyright laws for particular electronic documents “since technological changes have historically, represented challenges for existing forms of copy protection” (Howard, 1996, p.404).

Nature of copyright laws makes it difficult to say if certain situation is or is not copyright infringement. However, copyright principles can serve as guidelines for professional communicators when dealing with copyright questions. For that let’s return to scenarios presented at the beginning of the chapter.

Scenario 1
Central Questions presented earlier were (1) does such a reproduction fall under the doctrine of fair use and (2) who owns the copyright on the image?
Answer: This case is not a case of ‘fair use” of the original work because reproduction is not being made and used for educational, news reporting, or critical purposes. Even thou original image was manipulated, it’s still be “legally considered a derivation of an original work”. The member of the documents design team should receive permission before reproducing and manipulating the photograph. He/she should contact publishing house which owns the copyright of the original rather than using the magazine’s reproduction.

Scenario 2
Central Question presented earlier was (1) should technical writer go ahead and copy the software since office has paid for the software?

Answer: There is twofold answer in this case:
A. If company has only limited license to copy (usually for purpose of creating backup copies during installation process) the program, copying the software would be a violation of the law. It’s a good idea to check exact terms of licensing agreement to avoid such violation.
B. If company owns “site license” rights to copy software on to several machines or install software on their networks, then software can be copied on to the second system. The exact number of copies that are allowed to be copied should be specified in the licensing agreement and followed accordingly.

Further explanation: Often there is misconception that if company or individual own a copy or software they can use them as they wish. However, according to the copyright principles “owning” a text is not the same as the right to copy the text. We may own an actual physical copy of a book, photograph, computer, disc etc but that does not give us right to copy unless we have purchased license to copy the item.

Scenario 3
Central Questions posed earlier were (1) whether use of quote passage from the e-mail message is protected by the fair use clause and (2) whether the author of the message, the owner of the discussion group or the university that hosts computer groups is the copyright holder for the message?

Answer: Quoting from the e-mail message would probably be fair use regardless of the type of group. If group has ISSN, the fair use conditions would apply. If group does not have ISSN then most secure and ethical would be obtain the permission of the e-mail author before quoting the message. Also it would be beneficial to contact discussion group owner in regards to the quoting practices.

Further explanation: Principle of fair use allows reproduction of short passages for new reporting or in the texts of academic journals such as Technical Communication. Situation here is complicated by the technology involved. According to fair use clause in addition to purpose and amount of work to be copied, “the effects of use” need to be taken into consideration. By using the e-mail message, the author might feel that she was not given the opportunity to publish the work through more traditional means where possibility of remuneration is much greater. On the other hand, sending an e-mail to an electronic discussion is also a form of publishing.
There is no clarity in copyright laws in regards to text sent and distributed in electronic format and it varies from case to case. If the discussion group has received ISSN number it has copyright status. Often, the discussion group’s owner states that copyright belongs to author of the postings or messages sent or group members might have agreement not to cite each other’s messages outside the discussion board.

Scenario 4
Central Questions presented earlier were (1) who “owns” the messages that employer sent? And (2) and what rights does ownership of the messages entail?

Answer: This is not a copy right violation because copyright law principle does not give author “…unlimited property right” to their texts (Beard, 1974, p.382)” (Howard, 1996, p.406). Usually company has sole copyright to the texts that employee produces while being employed by the organization. In this case, if the company’s resources were used to produce emails, the company has rights to use those messages. The above case addresses more issues of privacy than copyright infringement.

Further explanation: In some cases (particularly in university setting), an institution may only receive portion of the remuneration. This is due to the fact that work of the writer was done partly using institution’s resources and partly done on employees own time.

Scenario 5
Central Questions presented earlier were (1) whether the university is entitle to some royalties received for the stack’s publication and (2) whether using the data but not the organization or expression from another work constitutes a copyright infringement?

Answer: If university’s resources were used to develop the stack, the university should get remuneration for use of its facilities. The faculty member should agreed to share percentage of profit with the university. Answer to the question of whether reorganization of data complied in another source constitutes a copyright infringement is no. Faculty member’s use of information is not a copyright infringement because the original expression of data has been avoided. Copyright law also indicates that data are part of public domain. The safest way for the faculty member, however, would be to negotiate some kind of financial arrangement with the persons holding copyright to the reference materials.

Further explanation: Two fundamental principles of copyright law come into conflict in this scenario. One of the principles is that authors and publishers are expected to make profit from their publications, on the other hand there is principle that “ideas and knowledge cannot be the property of any one individual and that only the expression of the ideas belongs to the author or copyright holder” (Howard, 1996 p. 407).

As in many cases that involve electronic texts today there is ambiguity on how Congress and court will deal with changes to the current copyright law. It’s possible that due to hypertext and electronic databases it will allow users rather than authors to determine the ultimate organization and shape of these electronic texts This is fundamentally different from the present copyright law.

Conclusion
As the scenario showed, the new electronic environment in which writing professional must function makes intellectual property and copyright issues more a part of their everyday experience in the workplace. Writers must know the basis of the copyright laws better than ever. The scenarios do not offer how one might turn out in a court of law, but it should offer writers how to avoid copyright infringements.

Howard - Who Owns Electronic Texts

2008-03-21T11:31:00.000-07:00

Introduction

At first glance, the title of the essay reviewed here Who “Owns” Electronic Texts doesn’t seem all that out of the ordinary in the year 2008. But that’s exactly the point of including the article in the collection Central Works. Tharon Howard, in the essay, is very forward looking in his assessments of the legalities of copyright and intellectual property rights of authors in the electronic age. One could say that the essay was just slightly “ahead of its time.”

Historical Context

In his review of the history of copyright laws, Howard sets out to discover how electronic means of communication such as digital imaging, software licensing, email communication, and hyper text language hold up to the letter of the law.

Historically, there are three theories of textual ownership that have pervaded for centuries:

1) Authors have a natural right to “own” their work
2) The laws of nature and absolute truths cannot be “owned”
3) Socially-constructed truths have no owner

These theories of ownership were really first challenged when the printing press was invented and books became inexpensive to make and distribute. Ironically, it really wasn’t the author’s ownership that brought about the first copyright laws but rather the publishers right to produce copies. The publishers banded together in a sort of loose union called the Stationers Company and attempted to enforce their own copyrights by allowing certain publishers unlimited rights to produce certain texts. They even established a sort of “book police” that searched out and destroyed all illegal copies of texts.

The U.S. Constitution addressed the issue of the unfair advantage that the Stationers tried to hold on to when it established copyrights that favored the author in Article 1, Section 8. This gave authors the exclusive right to their intellectual property – sort of. The ownership of authors was established for a certain amount of time after which the public then has broader use of texts. This in effect gave authors time to capitalize on their work both monetarily and by partnering with publishers and researchers to further their work.

Now, the laws of the United States in a few ways also address the concept of fair use:

o Texts may be reproduced in limited quantities for use in teaching, criticism, comment, news reporting, and in scholarship and research. Essentially, fair use allows copy of text insofar as it does not interfere with the commercial viability of the work. If a potential market is hindered due to copyright infringement problems will arise for the offender.

o Also laws protect the author’s expression of ideas. This means that, although certain universal truths may be found in scientific and math developments, it is right of the individual who arranged these truths in a formula to protect their intellectual property. i.e.) someone steals the code for a software program

The difficulty that we now experience is in the assignment of copyright and intellectual property laws to electronic forms of communication.

Examples of Electronic Copyright Questions

1) Photo reproduction – it is interesting that he was thinking about this twelve years ago as it is even more pertinent today in this age of digital photography. The verdict – always go to the publisher before using any portion of a photograph or image or better yet, purchase your images legally from iStock or some other image archive.
2) Software usage – always check the legal rights of the purchases before putting software that you did not purchase on your PC or Mac.
3) Quoting material from an email message – in general, check with the author of the message before using it. Many businesses and academic institutions have protected themselves by applying for an International Standard Serial Number (ISSN) number. The ISSN number identifies you as the owner of the text.
4) Private email message may be protected or they may not. Check the laws of the state you live in to see if your personal email is protected by privacy laws. I think we’ve learned since the writing of this article that nothing you do electronically is safe. In general, don’t put anything in an email that you wouldn’t want the whole world to see.
5) The fifth example involved something that I was not familiar with – Hyper Card stacks.
A hypertext programming environment for the Macintosh introduced by Apple in 1987. The HyperCard model consists of cards, and collections of cards, called stacks. You can connect the cards in various ways, and leaf through them the way you would with a set of Rolodex cards. In addition to data, each card can contain graphics and buttons that trigger other events, such as sound or video. Each object in a HyperCard system -- stack, card, text field, button, or background -- can have a script associated with it. A script is a set of instructions that specify what actions should take place when a user selects an object with the mouse or when some other event occurs. (from http://www.webopedia.com/TERM/H/HyperCard.htm)

This example really looks at the use of data owned by someone other than yourself and your rights to display the data in a way that is different than its original context. This, of course, is very pertinent in today’s world of instant information from the Web. The author’s advice – go to the source first and ask permission to use the data.

Conclusion

As technical communicators, we will collaborate frequently with other writers, engineers, developers and others. We need to be aware of the implications and consequences of the use of protected material. It is imperative that we keep informed of changes in copyright and intellectual property laws. If you have any doubt about the legality of what you are doing, stop and research the issue. One can never tell how a court will rule in these types of cases and it’s better to be safe than sorry.

Thank you, Vanda and Lance

"What Experienced Collaborators Say about Collaborative Writing" by Allen, Atkinson, Morgan, Moore, and Snow

2008-03-16T20:58:00.000-07:00

Introduction

While attending a 2003 professional conference for technical writing instructors, the author noted a shift in attitude toward collaborative writing since her 1987 article had been written. At this point she was asked to reflect formally on the 1987 study.

Although “collaborative groups were taken for granted as part of teaching writing as a process” [351] in academic circles, employers viewed collaborative writing as merely a way to divide the writing workload and/or to provide input as subject matter experts. According to the author, the employers’ perspectives overlooked the value of collaborative writing, which is the increased depth of understanding that arises when co-authors share ideas and develop a common sense of purpose and respect.

In recent years, numerous studies have focused on professional on-the-job writing, but the process and value of collaborative writing was never the primary focus:

A high frequency of professional collaborative writing exists (Faigley and Miller);

Collaborative writing is described by the way a document “cycles” from a staff person who researches and drafts the article to the person who edits the draft (Paradis, Dobrin, and Miller)

Collaborative writing can include a range of activities (Ede and Lunsford)

Individual planning and drafting of a document that is revised collaboratively (Odell)

A peer’s critiquing of a co-worker’s draft (Anderson)

The coauthoring of a document (Ede and Lunsford)

The research returned limited information about the process of collaborative writing and “the special characteristics of collaboration involving group authorship” [354]. The author’s research sought to investigate collaboration as it exists on the job with professional people who work together to plan, draft, and revise a single document.

Research Methods

Participants. The study participants were recruited by the research team and included a wide range of collaborative settings and projects. A total of 20 respondents representing 14 projects were interviewed, and they represented a variety of professional areas: business, university teaching and research, corporate research, government, community service, and a legal firm.

Interview Form. In order to compare responses, a structured interview form was developed. Questions “concerned the membership of the collaborative group, the roles played and contributions made by various group members, the writing process used, and the nature and frequency of group interaction.” [354] The final interview questions evaluated the respondents’ opinions of the final document and the collaborative writing process.

Respondent Interviews. The interviews were performed by a pair of researchers and were recorded. The respondents were asked to describe a “particularly memorable” collaborative-writing experience. The term “particularly memorable” was not defined, and the respondents were not asked to define why the experience was memorable. During the interviews, the respondents were asked to describe as much detail as possible along with their observations and evaluations of the experience.

Analysis. The first stage of analysis involved the demographic information (who, what, where, when, why); the second stage provided information about the collaboration process.

Research Findings

Demographic Information. The author recognizes that although the small sample size does not answer all of the research questions, the results do allow some “tentative conclusions concerning the people, tasks, and processes involved in collaborative writing” to be drawn. [355]

The tasks respondents chose to report on included a wide range of projects: proposals, books, articles, goal statements, reports, and legal briefs. Of the 14 groups surveyed, nine were made up of people whose background, training, and specialties differed.

Information about the Collaborative Writing Process

Group Writing Processes. All groups reported planning the project as an entire group first, which was also reported as being the most satisfying part of the collaborative process. The planning process was most often followed by periods of independent writing. The draft stage was most often assigned to people according to areas of expertise. Interestingly, the two groups that attempted to draft as a group were unable to complete the task, and both groups ended up assigning the writing task to one of the team members. Only one group reported drafting together as a group “word by word, sentence by sentence,” [357] but it should be noted that this group has written collaboratively for 15 years. Like planning, revision was also widely reported to be a group process and caused group members to think of new ideas and perhaps change some old ideas.

Group Interaction. The groups met frequently during the planning phase and most often in a face-to-face manner. As previously mentioned, drafting was most often completed individually while the revision process brought the group together again. The authors found three characteristics of group interaction noteworthy: 1) group members “consciously or unconsciously assumed the role of audience”; [358] 2) conflict occurred in all of the groups with a varying range of tolerance among group members; and 3) three of the groups used computers versus meeting face to face.

Group Decision Making. Decision making was shared in two ways. First, any member was able to oppose any decision made by the group and was not affected by the leadership style of the group. Second, the decision-making power was shared within the context of the group and its related project and did not extend to other contexts. An important note, in my opinion, is that a member’s right to question a decision did not mean a change would be made: “the decisions made within these groups were ones that all members could accept, even though they might not entirely agree with them.” [359]

Group Leadership. Most of the groups were organized around a leader who primarily offered organizational assistance. In nine of the fourteen groups, leadership was established by seniority or rank.

Respondents’ Observations on Collaboration

The writers interviewed for the study found the benefits of collaboration worth the costs; the costs most often mentioned were time and ego. All respondents felt the documents they produced were better than if they had been produced by an individual (particularly large, complex projects).

Discussion

Functions of Conflict. Although many group members were uncomfortable with conflict, the members nonetheless recognized that conflict contributed to creativity and to the quality of the document. Irving Janis “found that failure to allow for the development of opposing views within the group could produce such defective decision making that the overall value of group effort was lost.” [360]

Distinguishing Shared-Document Collaboration. The collaborative writing process exhibited three distinguishing features. First, a single document emerged at the end of the collaborative writing process due to shared goals and a unity of purpose by group members. Second, communication is a two-way interactive process and is completely different than a supervisor/subordinate type of relationship. Third, all group members have decision-making power and share the responsibility for the final document.

Group Typology. The groups interviewed were brought together because the size of the task required extensive labor, and/or the size of the task required multiple areas of expertise, and/or one of the goals of the project was to unite opposing perspectives.

Questions

The authors recognize that since the sample size was small, only partial answers were provided. Furthermore, the authors identified numerous areas for future research:

The respondents only reported on successful collaborative projects. Therefore, what are the aspects of “failed” collaborations

What sort of leadership is the most productive in the collaborative-writing process?

How does the type of task impact the collaborative process?

How is technology impacting the collaborative process?

A large percentage of groups had academic affiliations. What collaborative processes occur in other arenas?

What is the interaction between the hierarchy of an organization and the hierarchy of individual group members?

Lori Hood and J.J. Carlson

Central Works: Writing and Database Technology

2008-03-15T19:08:00.000-07:00

WRITING AND DATABASE TECHNOLOGY

NOTE: Article originally written in 1996

Data reports refers only to printed reports that are composed of both tables of numbers, words, or both. Tabular reports are the most common.

Reports consisting of data tables are vital to almost every business function. These reports are used by marketing, budgeting, production, and sales. This means many people may require many different versions of the same report, catered to their own personal needs. These reports can be intended strictly for the specific person reading them, or for a general group of readers.

The value of reports is organized record keeping and problem solving. However, many businesspersons lack the proficiency to generate a form and content that directly address a pressing business problem. According to a survey, managers were spending almost half of their work year looking for such data. Often, current reports would need to be adjusted and mathematically figured so that the new reports actually did provide the correct data. This process can be very frustrating and little attention is given in either business or in technical and professional writing classes to building people’s skills in writing effective data reports.

To develop these reports, writers have to transform raw data (“facts”) into meaningful information for a given context, audience, and organizational purpose, and it must be communicated in an effective way. This transformation is a rhetorical activity. People learn about data reporting, not through specialized courses, but in computer training classes, therefore stressing technological skills over rhetorical. This sends the message that knowing how to operate a technology is commensurate with knowing how to use it to its full advantage to achieve a purposeful exchange of information.

Data reporting demands a dynamic interplay between a writer’s rhetorical and technological skills. As such, it should have a place in technical and professional writing classes. The purpose of this essay is to explore unique skills and knowledge that data-report writers need to learn in order to produce effective data reports. Mirel argues that if data reports are to serve readers’ needs for record keeping and problem solving then writers’ technological skills must serve their rhetorical aims and strategies.

DATA REPORTING AS COMMUNICATION

To analyze the interactive rhetorical and technological competencies involved in data-report writing, Mirel first presents a framework for understanding the communicative dimensions of report writing. Historically, data tables have been associated with scientific rationality. However, this asocial view of tabular data ignores the inescapable rhetorical intentions and practical consequences of retrieving and reporting data. Many researchers argue that facts are not simply transferred from senders to receivers, but rather that it is based on a relationship between readers and writers. This relationship-based view of constructing knowledge casts a new light on the writing of data reports.

Many composition specialists examine computer literacy and electronically produced information through this constructivist lens. However, they omit databases and nonlinear tabular communications from the technologies they examine, such as word processing, desktop publishing, electronic conferencing, and E-mail. Some research in rhetoric, visual design, and human factors, however, does focus on database-related communications. This research reveals that

Key rhetorical strategies inform data searches, retrievals, and reporting;
Rhetorical and technological skills mutually support and shape each other; and
Designs for functionally effective tables must facilitate readers’ strategies for answering business questions.

Key Rhetorical Strategies Inform the Searching for, Retrieval of, and Reporting of Electronic Data

Sullivan (1986) concludes that rhetorical invention is the defining feature of electronic data searches. She finds that searchers must possess the following skills, all of which involve invention processes:

Knowing the meaning of “invisible” data that are stored in the system;
Focusing on what is at issue in a communication situation (stasis); and
Determining the most effective topical orientation of a particular purpose (topoi).

Rhetorical invention also comes into play in reporting data. Research finds that writers do not experiment with enough formats. Therefore, they rarely produce the best format for their exact purposes. As on overview of qualities necessary for effective data reports, Zmud (1978) identifies four characteristics that are implicitly rhetorical, as noted in the parenthesis:

Quality of information (selecting appropriate and relative data);
Accuracy and sufficiency of information (selecting the right scope and detail);
Quality of format (sequencing, ordering, and chunking information effectively); and
Quality of meaning (evoking emphasis, patterns, and relations through logic and layout).

Skills in Rhetoric and Database Technologies Support and Shape Each Other

A number of studies show an inextricable link between rhetorical and technological strategies in data searching and retrieval. Researchers find that unless people know (or invent) (a) the meaning of the data, (b) the significance of data relationships, and (c) the right level of detail for a questions, they will have difficulty understanding the basic program logic of search principles and data structures.

Designs for Functionally Effective Tables Must Facilitate Readers’ Strategies

Developing effective tabular displays of data should lead writers to research on visual rhetoric. A list of such research reports is found on page 384. These researchers emphasize the need to design tables to answer questions that readers will ask. There are three distinct levels of questions and answers: elementary, intermediate, and overall. The goal for designers is to choose a tabular image that answers the majority of questions the information is capable of generating.

Functionality is also important in designing tables. While simplicity works best as an aesthetic preference, it is not always the best strategy for displaying information. Designers should realize that the effectiveness of a table does not depend on how much information it includes, but on how information is layered and ordered to facilitate readers’ interpretations. Developing effective data reports requires writers to be adept at rhetorical strategies for invention, arrangement and delivery, and to understand the logic and capabilities that a program offers for defining, searching for, and retrieving data and for organizing it into printed reports.

METHODOLOGY

To study the rhetorical and technological skills involved in data reporting, Mirel analyzed readers’ reported responses to the actual data reports that they receive and use at work. From these responses, she inferred some knowledge and skills that writers should have to develop effective reports.

Mirel had 25 respondents – project administrators in a national research laboratory. She gathered information on their responses to a report that they received each month. The report was generated from a mainframe financial system. The respondents used the report for tracking costs, managing accounts, and assessing budget over- and under-runs. Mirel conducted a semi-structured interview with the respondents that usually lasted an hour. She asked the respondents the same four questions; then she analyzed the participants’ combined responses for patterns in their strategies and purposes for analyzing the report, for their satisfactions and dissatisfactions with the report, and for their methods of overcoming problems with it.

Mirel showed that the respondents are uniformly dissatisfied with the report and use the report for the same general purposes.

RESULTS

Each month, respondents use the report to answer four central cost-accounting questions: (1) Are all the changes legitimate? (2) Where do high or unusual charges come from? (3) What are the differences between actual and budgeted costs? and (4) Which accounts are likely to run over budget (and how should resources be allocated to avoid that overrun)? The respondents criticized the reports with the following six reasons:

Information overload: the report has too much data.
Overly narrow content: it does not give a big enough picture of cumulative months.
Random data: it does not group or emphasize data for easy interpretation.
Unprocessed data: it does not calculate key relationships such as variances between actual and budgeted costs.
Unintelligible data: it labels rows or columns with terms that have unclear meanings.
Unpresentable data: it has low legibility and layouts with little difference between figure and ground.

Some respondents rearrange their information in some ways, but six of the respondents rearrange their report either on their own PC or in the interface program. These six are considered writers as well as readers. The other respondents believe they lack the technical knowledge to reorganize their reports.

DISCUSSION

Most respondents felt that they lacked the technical knowledge to adapt the software or applications to their specific needs. They need to know how to translate their rhetorical aims into a technologically produced document.

To develop effective reports, writers must learn the database capabilities that enable them to achieve their rhetorical aims for invention, arrangement, and delivery.

The Aims and Processes of Invention in Data Reporting

The success of data reporting depends on fundamental invention processes, namely writers becoming familiar with a subject, identifying issues and questions that concern readers, understanding the optical orientations that address these concerns, and selecting content accordingly.

The respondents’ unhappiness with the report can be traced to many invention issues. The report does not select and display key data relevant to their needs. Many of the respondents wanted other content as well, such as more verbal description about purchases. The report writers need many technical competencies in database applications, but databases are one of the most complicated technologies for lay users to manipulate for their specific purposes. Writers also need to understand if the connections among data that make sense, practically, for solving a business problem are technically feasible. It is only feasible if the data are set up in a special way to allow writers to retrieve data from different databases.

Once the databases are created, report writers have to know how to frame their searches for information in statements that a program will accept and process. Writing search statements involves abiding by the syntax of a program and, at times, becoming creative with its search logic.

Finally, report writers’ technological strategies include assessing whether the data they retrieve are in fact the right data for their purposes. Database users rarely check the answers yielded by a search “failing to search for other levels of data which could supplement or contradict what they already found.”

The Aims and Processes of Arrangement in Data Reporting

One of the greatest challenges for report writers is to choose an appropriate organizing logic for tables that are multifunctional. They need to know that data reports for marketing purposes may take as many as five drafts of a table before a report convincingly shows a supervisor that it is best to target a very small group of low-volume customers because they generate the highest revenue.

Rhetorical purpose should determine whether the best display is a table or some other graphic form. The preset order of columns results in separating data that these readers want to compare. The row headings also do not accommodate the “cut into the data” that some respondents want to take because of the unique structures of their projects.

The Aims and Process of Delivery in Data Reporting

Delivering information in effective visual designs involves giving readers easy access to the data and data relationships relevant to their concerns. Reports used for reference usually display large amounts of data in a small amount of tabular space. Legibility is paramount.

Reports used for problem solving need designs that draw readers’ attention to key information and that help them to distinguish important types and groupings of information. Table displays should create for readers’ paths through the table so that readers perceive particular groupings of data as individual “locales” that they may access at random and read as self-contained information. Type size, style and variation are vital for emphasizing specific elements and relationships; positioning and locating data support people’s conventional strategies for reading left to right and top to bottom. Use of white space is important in creating tables that maintain readers’ understanding.

IMPLICATIONS FOR TEACHING AND FURTHER RESEARCH

For invention, arrangement, and delivery, writers of data reports must dynamically relate rhetorical and technological strategies to produce accessible and purposeful tables of information. The effectiveness of data reports, as judged by readers in an actual communication context, hinges on writers having chosen and implemented conceptual and visible displays that answer readers’ concerns and questions.

Mirel suggests introducing undergraduate students to a curricula including technical and professional writing. It would be especially beneficial if the writing and computing teachers could provide some collaboration for the students and can include team teaching to show how both areas cross over.

To better understand the rhetorical and technological competencies involved in data reporting, researchers need to investigate the ways in which various features and functions of database applications enhance or constrain rhetorical choices. More studies should focus on report writers and actual readers in natural work settings, closely assessing the qualities that characterize effectiveness for different types of data reports and the processes involved in producing them. These studies need to extend long enough for researchers to iteratively test writers’ choices and revisions against readers’ actual uses of a document.

Summary of Chapter 8: Barker

2008-03-15T07:52:00.000-07:00

by Gary Teagarden and Jennifer Bruns

Conducting Usability Tests

This informative chapter covers usability testing for document and software design.

There are 10 steps in the process of usability testing:

1. Decide when to test
2. Select the test points
3. Choose the type of test
4. Set performance and learning objectives
5. Select testers and evaluators
6. Prepare the test materials
7. Set up the test environment
8. Record information accurately
9. Interpret the data
10. Incorporate the feedback

1. Decide When to Test
You can test at any time during the nine stages of the documentation development process. Usually you test after you have a draft finished so you can see the areas that need testing. But you can test during the three major phases: design, writing or development.

2. Select the Test Points
A test pint is an issue or feature of a document that might interfere with the efficient and effective application of a program to a user’s work activities. Test points fall into two areas: problems with content and problems with document design. Test points could be body text size, heading size, cropped screens vs. whole screens, cues for steps and page orientation.

3. Choose the Type of Test
There are three types of tests—dependent upon the test points selected in step two.
Can-they-do-it test
Can-they-understand-it test
Can-they-find-it-test

4. Set Performance and Learning Objectives
Because you want your tests to measure actual behavior, you must come up with numbers that correlate with the kind of performance you want from your users. These are often called operational objectives. There are two broad categories of performance objectives: Time-related and error-related.

5. Select Testers and Evaluators
The tester is the person who administers the test, arranges the meeting with users, sets up the test situation, records the test activities, and so on. The evaluator is the person taking the usability test.

6. Prepare the Test Materials
Depending on the complexity of your usability test, the written and other materials you supply for testers and evaluators can get complicated. See Tables 8.5 and 8.6 (P.248-249) in the text for a comprehensive list of potential test materials.

7. Set Up the Test Environment
The environment for your test may range from the user’s work environment (the field) to a controlled laboratory. Your best chance to learn about actual use in the context of the user’s work and information environment comes from field testing.

8. Record Information Accurately
Recommend using voice and video recorders, plus take copious notes so that you don’t miss anything.

9. Interpret the Data
Interpretation requires you to take into account all the elements that can go wrong with testing so that you get clear results.

10. Incorporate the Feedback
Following the interpretation your data then the next step is to incorporate the results into your final design.

The author talks about the test paradox: The earlier you test the weaker the results but the easier it is to make changes; the later you test the better the results but the harder it is to make changes.

Some large companies, such as IBM have full-blown usability labs replete with two-way mirrors, video cameras and eye-tracking devices. Ironically, often the best results from usability testing comes from field testing. In addition, field testing is less expensive. But field research poses issues of time, politics, budgets, ethics, and legality that require you to proceed carefully.

Campbell, Chapter 8, “Did I Forget Anything?”

2008-03-14T10:41:00.000-07:00

Introduction
Be thorough! The writer is ultimately responsible for mistakes and errors in completed projects.

Creating a Perfect Document
Be sure that you use a review process to ensure that your document does what you want it to do.
There are five types of reviews:
1. Verification (e.g., accuracy)
2. Validation
3. Editing
4. Proofreading (e.g., spelling, punctuation)
5. Approval (e.g., getting clearance)

It is important to keep in mind that these reviews should be done in the above order so that the most critical issues are addressed first.

Can I combine a review?
You can, and sometimes it is effective. However, sometimes this is a more demanding and requires greater skill from the reviewer. When you try to compress all the reviews into fewer steps, something will usually suffer. If you choose to combine reviews, be sure your reviewer knows what you are really looking for from them – whether it is punctuality mistakes or accuracy of the information – they need to know. Having multiple reviewers is another way to ensure that more errors are found in less time. Failure to plan adequate review time is a guarantee that a document will go out with mistakes in it.

The rest of the chapter describes the review steps in detail:

Verification
• Checking for accuracy – information up-to-date, correct, dimensions accurate, eligibility requirements correct, etc.
• Various methods: compare the final draft to the original draft, check it against source documents, confirm numerical and statistical data, or assign a content expert to do the review.

You can combine them or perform them separately.
• Especially important in procedures, where perfection is vital.
• Sometimes, verification can be combined with editing, but it’s usually best if these are done in a separate review. You must be in an “accuracy” mindset when reviewing facts and important data.

Validation
• Checking for usability – policy or procedure understandable, well delivered, does it work in the real world, etc.
• Make sure the concept is understandable. Read the policy completely through to see if it makes sense or if anything is missing. Some writers can do this themselves, but it is easier if there are at least one or two other reviewers.
• Policies can be difficult to validate, as they’re often ambiguous or hard to measure. Usability testing is the best way to test a policy, so use this when possible. You can watch or gauge your reviewer’s difficulties or confusions and make the changes when appropriate. Honest feedback is important.
• Validating procedures does take longer because you’re actually testing the steps and sequence. Again, more eyes make for a better review. Use walk-throughs, observation, focus groups, and surveys to gauge responses. All of these steps require that you go through the basic steps of preparation, testing, debriefing, and documentation.
• Look for anything that indicates a problem on the user’s part: hesitation, guesswork, rereading, page flipping, or improvisation.

Editing
• Most are familiar with this – once you’re sure the content is correct and understandable, you can move on to editing. Editing presents a unique challenge – improve the policy without changing the meaning.
• Use this review to check for format, wording, consistency, flow, cohesion, layout and visual appeal.
• Number of edits depends on the document and project. Use the number you feel is appropriate.
• Approach editing with great precision. Know what you’re editing for, and plan time to do it. Make sure you are going to be uninterrupted when editing so that you can give the document your full attention.
• Keep an eye out for detail for important matters mechanical correctness, not trivial ones. Be sure that you are not looking for small changes like typographical errors in editing – save that for the proofreading phase.
• Review the page layout, look at the formats, consider the design elements, and scrutinize everything for consistency and logic.

Proofreading
• Proofreading is an important, although not necessarily the most enjoyable, task. Most writers consider proofing insignificant. However, if you do not spend time proofreading your document, you may let small mistakes get through. This can question your credibility with your audience. Consider proofreading your final walk-through of your document.
• Decontextualizing is the secret to effective proofreading. Reverse the learned habit of reading for meaning and concept. Take the letters, numbers, and words out of context and consider them as strictly letters, numbers, and words.
• To proofread, you can try many different methods – read backwards, read aloud, read into a tape recorder, read with a partner, read diagonally, turn the page upside down, photocopy it, scan it, or take frequent breaks.
• 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. When proofreading graphics, be sure you view all details – enlarge the graphic, make certain all numbers are correct, every line is plotted accurately, every item is correctly labeled, and the information in the graphic is consistent with the text.
• The most common errors: transposed letters, duplicate letters, omitted letters, and substitute letters. All proofreaders also have their own ‘blind spots’ – know what yours are and make a mental rule so that you can remember what is correct.
• If you choose to proofread your own material, be sure you are very thorough. It’s best, however, to hand it off to someone else to proof if you can.
• All writers have deadlines. Make sure that you always allow some time for proofing, no matter what.

Approval
• Getting clearance is the last step of documentation review. Send your document to the designated approvers when you’ve completed the above four review steps. However, be sure that you keep in constant communication with your reviews throughout your documentation process. Ask for their input, or consult with them if you need to – approvers don’t like surprises.
• It is best to have a formal procedure in place for approving documents. Make sure your procedure outlines time frames and the approval cycle so that there are minimal questions from the approvers. Once these approvers receive a draft, be sure they know you are expecting their input and that all comments will be considered.
• Slow response time is usually a problem. Most managers and approvers are busy, and will often be swamped with other work and your review will just be one extra thing. Strive to make your document approval an easy process by making a form that makes the approval quick and painless. See the sample form in Chapter 8 for ideas.
• Sometimes approvers disagree on documents – don’t let this bother you. Opinions are what you are looking for with your document review, and it is better to get these opinions and thoughts out in the open before the policy is in place and it then becomes more difficult to change. Stay on top of the approval by coordinating and communicating amongst the approvers. Analyze their responses and look for validity and set up meetings if your approvers require one to come to a consensus.
• You can also have unofficial approvers for your document. Frontline managers, group leaders, or even informal clique leaders can be key supporters for the document. Keep these people in mind in your writing and review process as well – always keep those lines of communication open.

The Critical Decision: Who Reviews?
It is always better to have others review your work. Their eyes are fresher and they are not too closely tied to the doc. Sometimes, it is not always possible to have other reviewers, and when you MUST review your own work, you’ll have to exercise twice your normal discipline.

Submitted by Team 1: Beeman & Xiong

Barker, Chapter 9: Editing and Fine Tuning

2008-03-13T11:30:00.000-07:00

1. Establish Project Guidelines
Everyone involved should understand their roles for each project, as well as the team goals. A person may be a combined writer/editor, a writer, or an editor. The four types of editing that should be covered in a project are managerial editing, substantive editing, copyediting, and proofreading.

2. Understand the Types of Editing
Managerial editing: Sometimes called the production editing stage, this type of editing involves the documentation planning and production.

Substantive editing: Sometimes called the developmental editing stage, this type of editing involves information and language editing.

Copyediting: This type of editing involves consistency and accuracy in grammar and the document's format.

Proofreading: This type of editing involves giving everything a final look to make sure there are no inconsistencies or errors.

Note: When editing help documents, online testing and editing is important to ensure proper setup of the document on the computer.

3. Plan Your Editing Tasks
Plan and schedule the editing tasks in the early stages of production. Take into consideration the amount of time needed to complete each task when scheduling editing work. Make sure that when editing, no other tasks are performed. It is not the job of the editor to perform any of the writer's tasks, and it could back up the schedule if other tasks are worked on when they shouldn't be.

4. Develop the Appropriate Editing Forms
Develop and use editing forms to standardize editing practices and ensure efficient communication among multiple editors. Of particular importance is the style sheet (a running list of style decisions that have been made for the current document) and the style guide (a higher-level document that broadly defines the style of the document class or organization). Once these documents have been developed, encourage their use.

5. Conduct Editing Sessions
Sooner or later, you will sit down with the document and begin editing. Find an environment that maximizes your ability to concentrate. For most people, it must be absolutely quiet, with no disruptions. Use an editing checklist to make sure you don't skip any editing tasks--especially important when editing your own writing. Try editing with a partner--two brains are better than one. Also consider working on each task for only a short time. Your attention will be less likely to wander. Use multiple, separate editing techniques, rather than trying to catch everything on the first pass.

DISCUSSION

Editing Graphics
Figures and tables are often the first things a user will look at. The editor must ensure that the figures and tables are appropriate and accurate and that they match the document's style. Avoid cluttering screen shots with arrows and callouts--they distract when overused. Ask yourself, Will this figure help the user understand the information? Is there a better way? Know your audience.

Writing v. Editing
Writing and editing are completely separate tasks. If you are the writer and the editor, try to let the document cool off before you begin editing it. You'll need some distance to make unclouded decisions about your own work. If you are the editor of someone else's work, give them suggestions but avoid researching and writing for them.

Crossing Cultures
If your document will be read by non-native English speakers, try to make it easy on them by using simplified English. Simplified English stresses the active voice, the use of articles, the use of consistent language, and the construction of short, direct sentences. If the document will be globalized, used generic language that will be understandable across cultures. If your document will be localized, use language that is familiar to the culture the document is destined for.

When editing for translations, the rules for simplified English apply. In general, try to make it easy on the translator to render the text into a different language. This is complicated and requires specialized training and practice.

Editing Online Help
Editing online help systems is similar to editing paper documents, but there are some differences. Pay special attention to the index and links because these will be used heavily by the average user. Edit on paper and on screen because it is generally easier to edit on paper, but you need to see how the document works on screen as well. Make sure you have an up-to-date topics list so you can check the completeness of the help system.

Knowing What's Correct
Much of the time, you won't. Consult various authorities to arrive at a consensus opinion, then stick with it. Above all, ensure that your document achieves the document's goals.

Working with Others
1. Be Positive; Don't Be a Pain in the Neck
2. See #1.

Barker Chapter 7 - Useful Reviews

2008-02-29T19:09:00.000-08:00

One word could sum up Barker's chapter seven on useful reviews: inclusiveness. What exactly do we mean by inclusiveness? It's the process of bringing a wide variety of stakeholders (reviewers) together in the documentation process. Bringing these stakeholders together allows the document's author/originator to produce a piece that is truly for the user. During this process, the document goes through a procedure of envisioning, planning, designing, revising, and editing--all on a realistic schedule. But in order to produce a quality document, honest input from all those who are part of the review team will allow the final product to achieve maximum utility.

The Review Process

Reviews can be time consuming. A thorough review process begins with a statement of intent that the document's authors can circulate at the initial stages of the review. This statement puts the document in the proper context for the review team.

The authors can offer the review team a variety of review types:

Managerial
User
Technical
Subject Matter
Editorial
Sponsor

See Table 7. 4 for a description of these review types

In order to keep the reviewer on task, it is best to give each reviewer a list of specific questions to complete which are pertinent to their area of involvement only. This will keep the reviewer focused on their area of responsibility.

Time is important to the process and schedule, thus it is important to make sure the reviewer has enough time to complete their own portion of the review.

When you send the document to the review team, there are a couple of options for distribution. Each of these options has its advantages and disadvantages. For a complete listing of the attributes of each distribution channel, please consult the text.

Sequential circulation - begins with one reviewer who subsequently passes the document on to the next reviewer in an orderly fashion. Usually there is a routing note attached to the document so that the order of review is pre-determined. This is a less expensive way to do things (only one copy is needed) but it can be very time consuming if the document become buried on one of the reviewer's desks.
Simultaneous circulation - involves the distribution of multiple copies of the document to be reviewed circulated at the same time to all reviewers. This method, of course, can be faster because each reviewer works independently at the same time.

The most significant difference between the two methods is the manner with which the reviewers supply their remarks. In sequential circulation, the reviewer will see the marks of the previous reviewer thus limiting the amount of marks that come back to the author. In simultaneous review, the reviewer is free to mark up all the aspects of the document. It seems that simultaneous review might yield a more thorough examination because each participant starts at the same point and must look at the entire document (free of other's remarks).

Be personal

The document's author/originator must always be aware of the fact that those people who make up the review team are doing him/her a valuable favor by lending their time to the review process. Because of this commitment from the reviewers, the originator of the document must keep a few things in mind:

Explain your review goals thoroughly when distributing the document for review
Reinforce the relationship you have with the review team (complement and thank them often)
Explain the benefits of participation on the review team (the final product benefits from each reviewers expertise)
Describe how you would like the reviewer to comment i.e.) marks, colors for each reviewer
Give the reviewers a firm date to return the draft to you
When the review is returned, make sure that you acknowledge each reviewer's particpation

Figure 7. 4 provides a good example of a review sheet that can be given to the review team

Final Discussion

It's imperative to know what you're asking for from the review team. Make sure that each reviewer understands the differences between:

Reviewing - uncontrolled environment with many comments
Testing - controlled environment with few participants
Editing - professional environment with a single editor

This chapter focuses on review only. Reviews provide the document's author with a quality end product because all of the project's stakeholders (reviewers) will have had the opportunity to comment on the document and the project will be kept on a tight schedule that management will appreciate.

The earlier you begin the review process, the better it will go because the important background information will be discussed more often with the team before the project becomes too involved.

Keep your review team informed and engaged and they will probably work hard for you. If differences arise amongst the reviewers, you must be diplomatic and fair because you will need the reviewers in the future. You can't afford to alienate your team.

Finally, consider doing a walkthrough with the review team at some point during the project. The walkthrough brings all the stakeholders together for a intensive, one hour meeting. The walkthrough, if kept on task, will allow the document's author/originator the opportunity to record and compile a great deal of information in a short time. This will shape and refine the document and give all reviewers the opportunity to collaborate. Most likely, the greatest benefit of the walkthrough involving many reviewers is the opportunity to shape the document in such a way that it will elicit minimal negative feedback in the final stages of review.

Our thoughts

The key to effective document review is a cohesive review team. Keeping the team informed in all phases of the review process will create a more comprehensive and usable document in the end. People like to be heard and it's not difficult to allow this to happen if you plan the review process from the beginning.

In summary, follow these five steps as review process guidelines:

Ask politely for involvement from reviewers
Explain why they are important to the project
Keep the team informed (always) not just when you need them
Thank the reviewers when they have completed their task
Show the reviewers the final product with changes

Thank you, Vanda and Lance (Team 7)

"Frameworks for the Study of Writing in Organizational Contexts" by Teresa M. Harrison (Central Works... Article 17)

2008-02-29T10:21:00.000-08:00

Preface
Harrison comments that, nearly two decades after this article was first written, she realizes "that the primary activities of communication theorists are to derive and synthesize" (p. 255). She recognizes not only how much of this essay was based upon other research but also that this essay was one part of an evolving communication theory that has since become "the status quo" (255).

Introduction
Most professional writing is done within the context of organizations. While the amount of writing varies in different fields, most college-educated working adults do some writing on the job.

Writing that is done on the job tends to reflect the writer's analysis of organizational policies and procedures, understanding of readers, and awareness of social and environmental constraints.

Studying writing in organizational contexts helps us to understand the relationship between how organizations work and how its members write. It might also help us to develop broader theories about the impact of social context on the act of writing. Finally, it helps students of writing to better analyze and prepare for writing in and for their organizations.

One major challenge to studying organizational writing is the necessity for interdisciplinary research. It requires an understanding of both composition theory and organization theory. This article presents several approaches to studying writing in organizational contexts.

The Nature of Context
Much of the research on writing has focused on the social aspect of writing. This includes not only studying the relationship between the writer and the reader, but also studying the environment in which the writer and reader interact. Whether an organization should be considered a rhetorical context depends upon which approach the researcher takes.

Context as Situation
In a traditional approach such as Bitzer's, rhetorical context is considered "a situation that constitutes an occasion for rhetoric" (257). The elements of audience, exigence, and constraints trigger an appropriate rhetorical response. In this approach, situations are objective and set. The people experiencing the situation are constrained by and respond to the situation.

In this approach, there is no need to analyze organizational context because rhetorical situations are isolated events that occur between individuals. However, Harrison contends that organizations do influence rhetorical situations because their unique policies, procedures, and members may limit the kinds of situations that may occur.

Context as Community
In the New Rhetoric, reality is not seen as objective. Instead, knowledge arises from rhetorical activity or social interaction; it doesn't exist outside of the knower. The knower's assumptions influence the way they view or understand an experience.

Individuals who share assumptions make up communities, and community knowledge may different depending upon the context of each community. When individuals communicate within a community, they are demonstrating that they belong or identify with others in that community. Because of shared assumptions, individuals within a community can understand each other, and that understanding further reinforces the sense of community.

While rhetorical activity can unite communities, it can also exclude other individuals. Those that don't share their knowledge or behaviors may be excluded. Because of this, shared meanings that are reinforced within communities can be analyzed.

In this approach, academic disciplines, such as science or composition, can be viewed as unique communities with specific characteristics. If this is so, then organizations too can be considered communities with unique characteristics that should be examined for rhetorical context.

Organizations as Rhetorical Contexts
From an organizational theorist's perspective, organizations are seen "as a social phenomenon constructed through the interaction of symbol-using organisms" (260). They are viewed as cultures. Therefore, a number of researchers have used ethnographic methods to study organizations just as they would different ethnic groups.

Two perspectives in particular are helpful for analyzing an organization's rhetorical context: viewing organizations "as systems of knowledge" or viewing them as "patterns of symbolic discourse" (260).

Organizations as Systems of Knowledge
One approach to studying organizational culture views it as a " 'system of cognitions or a system of knowledge and cognitions' " (260). As individuals interact in the organizational environment, they create and reinforce the beliefs around which their culture is based. In this approach, researchers attempt to understand how an organization's members create knowledge and how that knowledge is used to guide behavior.

The evolutionary model focuses on "the organizational-level processes by which knowledge is constructed" (260). It argues that organizations retain interpretations of experience that are positive or useful, and these meanings become the shared knowledge of the organization.

The social information processing model focuses on "the social processes by which knowledge is established and shared" (260). Organization members interact with each other, sharing their perspectives and attitudes about the organization. These shared ideas become a system of knowledge, referred to as a "paradigm" (260).

The basis of this approach is the belief that thinking and acting are related. Studying organizational knowledge can provide insight into members' beliefs and roles. A major challenge, however, is understanding how organizational knowledge affects the actions of individual members.

Organizations as Patterns of Symbolic Discourse
Another approach views the organization as a context for making and using symbols. Symbols may include the words and images developed around the unique actions, events, or objects of an organization. Studying the symbols that are commonly used in organizations can provide insight into the relationships between and the actions of an organization's members.

Symbols such as images and metaphors can reveal much about an organization's beliefs and even the way its members think. One example is the use of war metaphors to represent corporate takeovers.

Common words may take a unique meaning for members of an organization because of shared understanding. Examples are slogans, stories, or sagas that illustrate the beliefs and values that guide the actions of an organization.

In summary, the New Rhetoric expands the definition of rhetorical context beyond the rhetorical situation. It includes the larger environment, such as an organization, that sets the stage for rhetorical situations to occur. This consideration is necessary because an organization influences the beliefs of and symbols used by its members.

Implications for Research
One recommendation for applying these approaches is to examine the shared knowledge of an organization and how that influences the writing done by its members. The culture of an organization might influence or limit the writing methods used by members.

Researchers may also examine organization's policies regarding how to write, what to write, and who writes. Deviations from established policies might also reveal something about the individual writer's rhetorical choices.

The symbols used by an organization can be analyzed to understand the rhetorical choices that are available to an organization's members. Symbols can also be analyzed to understand how they contribute to the creation and maintenance of the organization itself.

Implications for Writing in Organizations
Writing for an organization can be challenging. Organizational writing requires that the writer learn about the culture of the organization. Without an understanding of the values, goals, and beliefs of an organization, a writer might not be able to effectively communicate with the intended audience. The organization may also have written or unwritten rules about writing that must be considered.

Considering an organization as a culture is helpful for performing audience analysis. If members of an organizations share beliefs and symbols, then the writer can better plan how to approach such an audience. The writer can also consider the characteristics of those who are not organization members and can write appropriately for that audience as well.

Analyzing an organization's culture is helpful for both new and old members. Those new to an organization can analyze its culture to better integrate into the organization and develop writing appropriate for the organization. Long-standing members of an organization can benefit from understanding the underlying beliefs of the organization and can better target the desired audience.

Finally, analyzing organizational culture can help writers of all kinds understand the social environment. Analyzing an organization's symbols as if they were text helps writers to understand the shared meanings that influence the interactions of an organization's members.

Conclusion
Both rhetorical and organizational theories can be used to understand writing in organizations. Both theories believe that discourse is based on social interaction. Discourse unites individuals with shared beliefs into communities, and the common knowledge shared by a community's members allows them to understand each other.

Writers can benefit from approaching organizations as rhetorical contexts because it allows them to better appreciate the unique beliefs and symbols used by each organization. They can understand both the shared culture of those in the organization and the differences of those outside of the organization. This is especially important for technical writers who interact with both technical specialists and the general public. It is also important for others who write for organizations because it helps them to understand assumptions, to challenge them if necessary, and to create new knowledge.

Submitted by Team 1

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

2008-02-28T17:53:00.000-08:00

What's the Secret to Creating Good Manuals and Handbooks

What to Put in a Manual or Handbook

Ultimately there is no formula for writing a manual. The manual will be written for a certain purpose and a certain audience. How do you present the manual? You want to present it in a way that the user will find it easy to use by not spending endless time looking for answers in it. the content must be in logical order, with a reference systme that's quick and easy.

There are seven design elements referred to as the front matter and the back matter. Many of the items in the list are so common that we do not give them a second thought when writing.

Table of Contents (TOC) Front Matter

An overview of what's in the book. It's the first impression readers have of the manual. If the table gives a good impression it encourages the reader to go on. If it gives a negative impression, such as crowded, confusing, or hard to read, it gives the reader that assumption the rest of the document is the same.

List of Illustration Front Matter

This is placed after the TOC and lists the illustrations and graphics in the manual. This makes it easier for the reader to find exactly what they are looking for instead of paging through the book.

List of Form Front Matter

The list of forms is like the illustrations list. The book also suggests that this could be placed in a forms index.

Introduction Front Matter

"This part of the front matter sets the stage ofr what's coming and orients the reader to certain basics about the manual, such as the purpose and scope."

Glossary Back Matter

This is a list of definitions that is used throughout the manual. It can be placed at the front or the back. Audience analysis can help determine whether you should use a glossary, what type, and how in-dpeth it needs to be.

Appendix Back Matter

Information that supplements the text belongs in this section. This information would otherwise confuse the reader while going through the manual. If the text is at the end of the manual they have decision to back and read through it.

Index

"The index is probably the most valuable "speed tool" you can give the reader" Its an alphabeical list of what's in the manual. When developing an index use terminology the readers use. Stay with realistic language and avoid corporate-speak.

The Production Elements

This is another area that tends to be overlooked because of familiarity. Main items to consider when deciding on production elements are: 1. How readers will use the manual, 2. Under what conditions they'll use it; and 3. How frequently they'll use it. There are six elements to consider.

Size

Standard 8 1/2 x 11 for most manuals. Smaller size manual tend to get lost among regular size materials.

Paper

Using a standard 20 to 24 lb. paper is adequate. If heavy use is expected a heavier paper is suggested such as 24 to 32 lbs. If the manual is being used in a production area, a water resistent or laminate type of page should be used. It is more costly, but it will save the cost of having to replace manuals more often or losing pages of the manual.

Color

3 color issues

1. Page color

2. Section color

3. Binder color

White is mainly used for page color because it is easiest on the eyes. But to make a section stand out, color would be a good choice. The example gives whas the blue pages in a telephone book for the government section. Binder colors also can make a stand out impression. If everyone else uses black, try another color to make yours stand out.

Binders

Inexpensive binders aren't always the way to go. They often fall apart at the seams or the rings break. One must consider the usage it will have when purchasing.

Usage of the binder should also be taken into consideration. a 2" binder requires 2 hands where a 1/2" binders needs 1 hand to pull off the shelf. If a person is on the phone all day the 1/2" binder makes the most sense. Split up the manual into 2 binders.

Always use 3-ring binders when you expect changes in content. Spiral binders can be used if there is to be not changes or minimal changes. Whatever binding system is used, be sure the pages will lie flat and are easy to turn.

Cover

If using a binder, get one that has clear envelope on the front to slip a page into and preferrably one on the spine. Manuals sit on the shelf with only their spines showing, so being able to put a title on the spine ensure that they will be seen and used more.

Dividers

Tabs divide sections. Buy sturdy tabs so they do not break off between section.

Article Summary: Charney’s “Empiricism Is Not a Four-Letter Word”

2008-02-27T20:11:00.000-08:00

Do empirical methods have a place in the scholarship of technical and professional writing? At the time this article was written (1996), an influential cadre of technical communication researchers had been calling into question not only the validity of these methods but also the moral and ethical character of those who used them. Basing their rejection of empirical methods on feminism and social constructionism, these scholars successfully forced quantitative research in technical communication out of the mainstream. With this article, Charney’s aim was to expose the logical fallacies of this movement, as he saw them, and to attempt to restore the reputation of quantitative methods. His hope was for a community of scholarship that valued qualitative and quantitative research methodologies in equal measure.

The Mischaracterization of Science

Although many critics of science merge objectivity, positivism, rationalism, and materialism (among other terms), Charney notes that these concepts can and should be separated and that many notable scholars have upheld some, but not all, of these ideas. Nevertheless, critics equate the quantitative approach with an ethos of self-interest and political status quo. By eliminating the richness of human experience from their research, empiricists are viewed as misrepresenting the true nature of the world as reducible and fully describable.

A key accusation against empiricism is that it is inherently sexist. Some scholars charge that empiricism reinforces masculine modes of knowledge and shuts out other, feminine, paths, such as intuitions, traditions, and personal experience. Charney counters that, contrarily, the pervasiveness of sexism in our culture has often been revealed through quantitative analyses and that empiricism has probably opened the door to many more people to join in the production of knowledge than were allowed to in cultures that privileged the elitist few. Because science is open and repeatable, it allows anyone to challenge it and add to it.

Indeterminacy

Critics also point to the fundamental contradiction in science that so-called “objective” methods are not really objective at all. In every data set, there is variance; in all methods, there are indeterminate sources of error. How, then, can scientists claim absolute objectivity? Charney concedes that “scientific knowledge and methods are, at least in part, socially constructed.” However, he says, this does not invalidate the central rationality of science. Science is a process, not a discrete, monolithic entity. Imperfect tools are used to continually improve our understanding and to create new tools that are less imperfect than their predecessors. Science is self-critical and self-examining—nothing stands that is shown to be false. To Charney, empiricism is what prevents a totalitarian ethic because it promotes a free and open exchange of ideas. This is in direct contrast to the characterization of science by the opposing side as an upholder of oppressive power structures.

What’s Really Objective about Objectivity?

As noted, critics often charge that science is not objective because its methods are socially constructed and inherently indeterminate. However, to philosophers of science, there is no contradiction between social construction and objectivity—it is largely a misperception of science that leads people to reject it. The social constructivist roots of science are evident in the way that scientific ideas and methods are tested and re-tested. No one individual holds absolute authority. Knowledge is arrived at through consensus via a community-based process. Most scientists do not see their own results as fixed, immutable truths, but rather as probabilities that lean in one direction or another. As a result, scientific articles are best viewed as rhetorical devices to disseminate results and attempt to convince one’s peers of the value of one’s work. This process results in ever-improving methods and knowledge claims. It is precisely this aspect of science, and not the “supposed neutrality or disinterestedness of individual scientists,” that defines objectivity in science.

How Researchers Treat Their Participants

Another critique of empiricism is the cold manner in which quantitative researchers approach their research participants. Critics equate distance with uncaringness, objectivity with amorality. Charney points out that “these characterizations smack of the worst kind of exclusionary identity politics” in that “they essentialize the researchers on the basis of their methods.” In contrast, many quantitative researchers care deeply for their research participants—deeply enough to remain distant and “cold.” This distance is what allows them to report accurately on what they observe, and what allows others to reproduce their studies and validate their results. The methods one uses cannot be used as a gauge of the moral character of those who use them. In that light, the supposed caring and compassionate nature of qualitative researchers cannot be ascertained purely through their own descriptions of their participants. Their reports are just as calculated as those of quantitative researchers—they must assume a particular “voice” in order to appeal to their readers (primarily, other qualitative researchers).

Objectivity Reinforces Collective Authority

Qualitative analyses are inherently situated in the place they were conducted. Studies that rely on qualitative methods are not generalizable to broader contexts, and the validity of these studies cannot be independently verified. Paradoxically, this lends absolute authority to the individual researchers because they are the only ones who can make claims about their own research. Although qualitative research is often viewed as democratizing and collectivist, the opposite is true. Quantitative research, conversely, relies on the community for its credence. And because quantitative research leads toward generalizability, the results of multiple studies build upon one another to form an interconnected web of understanding.

Toward a Synthesis of Qualitative and Quantitative Methods

Neither qualitative nor quantitative methods alone are sufficient to create a robust field of scholarship in technical communication. Both reveal knowledge in their own way, and both reveal different kinds of knowledge. Charney believes that, as a field, we should embrace all methods that have the capability of leading us to our collective goals.

Barker Chapter 6, Planning and Writing Your Documents

2008-02-22T18:14:00.000-08:00

This chapter provides guidelines for planning a documentation project, including a production task list for each of the nine phases of the process. Barker states, “The key to producing quality documentation is to follow a process” (174). The nine phases of documentation production are to:

1. Start the project
2. Perform the user analysis
3. Design the documents
4. Plan the documentation project
5. Write the alpha draft
6. Conduct reviews and tests
7. Revise and edit
8. Write the final draft
9. Conduct a field evaluation

Each phase builds on the previous one, and implies testing and other ways to check progress.

Descriptions of the Phases

1. Start the Project

Writers should start by getting to know the computer software in question, considering how the material should be adapted to the user’s needs. Some documentation projects may be written by lone writers. But often projects are created in teams. Both development teams and writing teams work to develop software documentation. The development (“cross-functional”) team develops the entire project and usually includes professionals with varied backgrounds and skills. The team might include managers, market and system analysts, programmers, and documentation specialists. Those on the writing team focus on publications: writing, editing, or testing documents. This team might include writers, editors, graphics designers and testers.

Once the need for the software is established, project documents are developed. Project plans list the goals and justification for the project, the types of systems already in place, needed user documentation, and preliminary schedules and task assignments. Program specifications describe software details such as the programming language and operating system. Market analysis documents summarize the results of user analysis, looking at the motivations of the software purchaser, rather than the software user. The information plan describes what manuals or help will be created to accompany the software, identifying the primary users and including preliminary user analysis. The management plan specifies the resources for completing the project, including a day-by-day strategy and work roles. It also sets meeting dates, milestones, and deadlines for the project.

Online help systems, which contain information about program operations, deliver information using the WinHelp or HTML formats, or in portable document format (PDF). Topics are arranged according to user activities. Online help system development is similar to tutorial development, but differs in several ways. User analysis focuses on workplace activities and the users’ familiarity with technology and help systems. For the writer, time is required to learn the authoring system that will be used. Special codes are required to link the correct online help topics to the user “requests” for help while using the system. Links, as well as content, must be tested. In addition, testing must be performed in different operating environments, such as Windows, Macintosh, Linux, Unix, Internet, and Intranet. Testing takes much more time.

One of the biggest challenges in online help development is in choosing the best authoring environment. Some of the better known authoring environments include Doc-to-Help, Sevensteps, Microsoft HTML Help 1.3 SDK, RoboHELP, and AuthorIt. Consider authoring environments in terms of what features will be provided to the users. Management features allow project planning, scheduling, and tracking, as well as reports. It is also important to be aware of the types of help formats they can support, such as Word or PDF, Windows Help, HTML, XHTML, Microsoft HTML Help, or Java Help.

2. Perform the User Analysis
User analysis involves interviewing and observing users to identifying their user types and learning preferences, as well as activities they will perform. This helps to determine which program operations should be included in the program manuals and help documentation. User activities will guide the groupings of topics in the table of contents (as opposed to a default manual, which records the functions of the program without regard to user tasks). User analysis will also give writers a sense of how familiar users are with help systems and what kinds of features they expect to see.

3. Design the Documents
Keeping the user's needs in mind, documents are outlined and designed. Choices are made on the document forms (tutorial, procedures, and reference) as well as which products will be used (training, guided tours, tips, etc.) Throughout the process, changes will be made as you test your documents with users and reviewers. For online documentation, a list of keywords and glossary terms begins to be created, as well as creating table of contents topics.

4. Plan the Documentation Project
A documentation project includes two parts. The design plan, also known as the "content specifications," describes what the manuals will look like and what they will contain. It should include (1) a description of the users and what kinds of tasks they will want to complete, (2) a discussion of the documentation objectives, and (3) a description of the content including outlines and the layout. The project plan has to do with how the manual will be produced. It will include deadlines of drafts, tests, and reviews, different team members' responsibilities, and knowledge resources. It will be necessary to estimate how long different project tasks will take. The documentation plan should be throroughly reviewed by managers, users, and clients. If the plan is complete and understandable, another writer should be able to follow it to produce the manual as you envision it.

In online help systems, the team will contain writers/experts as well as a developer who will handle the techncial aspects of the project.

5. Write the Alpha Draft
The alpha draft is the first complete document "including all the front matter, text, graphics, appendixes, indexes, " etc. The alpha draft will be tested, reviewed and edited.

In online help systems, the process involves writing content but also "creating links and interconnected relationships among topics". A special program called a help compiler, included with help authoring programs, can test the help system to discover incomplete links, missing cross-references and other types of errors.

6. Conduct Reviews and Tests
Clients, users, and others can review the alpha draft at the same time that usability testing is being designed and conducted. Feedback received can be used in making corrections and improvements.

Testing online help systsems is usually done after the whole system is completed because of the interconnectedness of all of the parts. The content must be tested as well as insuring that all links and pop-ups perform correctly

7. Revise and Edit
Information from feedback and reviews can be incorporated into the document. In addition, an editor can verify the document for accuracy and organization.

8: Write a Final Draft
Activities done in the previous two steps will help to greatly improve the document; the end result should be a camera ready document or online help that is ready for distribution with the program.

9. Conduct a Field Evaluation
The field evaluation, done by users and operators of the program, allows you to judge how well your product fits the needs of the intended user. Information gathered will provide input for the next project.

Field evaluation of a online help system can be done using email or feedback links that allow users to provide feedback. It can also be done using an electronic survey on a website.

In addition:
There are two main kinds of projects:

A stand alone project is one for which the writer is assigned or contracted to develop documentation for a program that has already been written. The writer can learn the entire program before having to write about it. However, they have no input into user analysis or the design of the project
A development project is more common in organizations that create software as their main products. Processes are in place for creating both software and documentation side by side. Writers can be involved in the project from the beginning and can provide input into the usability and interface of the project. The writing usually parallels the design of the product.

There are also three typical development methodologies in creating documentation:

The most traditional method, the waterfall method, follows user and program specifications throughout the process through a series of planned, organized steps. It is a more rigid process which doesn't allow as much flexibility if users' needs or program features change.
The rapid-development method allows teams to brings products to market faster. This method focuses on prototypes and usability testing; users' needs can be considered and adaptations made throughout the process.
The object-modeling method melds the two previous methods. If follows sequential development as well as incorporating usability tools, including a "use case" model, which is " a plan that tells exactly how the user will employ the program in the workplace." Programmers then focus on these tasks to create software that, when done well, will specifically fit the user's needs.

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

2008-02-21T20:04:00.000-08:00

Making a good first impression is important in order to draw readers in. Design can accomplish this. Keep in mind two things: simplicity and visual clarity. If the document appears to be easy to read, then it probably is. A reader isn't going to spend time reading a manual that doesn't look like it will be easy to read. Keep the design and format simple.

Twenty design elements should be followed when creating a document, including elements like font, spacing, margins, and white space. (See the Design Tip Sheet 6-1, page 223 for the complete list.) These design elements are effective because of the human brain and eye movement. Because the brain can only handle up to seven different items at one time, it is good to limit your documents to three different items, to make it easier on the reader. No matter what, don't go over seven items. Use the Rule of Three as your guide in document design. Eye movement follows four patterns, which help determine effective document design:

1. Line length: Readers comprehend about 40 characters per glance, so it makes sense visually to limit line length to 40 characters.

2. Words per second: The eye comprehends three or more words per second, so keep words simple and use headings and sections to enhance the message.

3. Words at a time: The eye comprehends two or more words at a time. Because the eye groups words together, the small words may get missed, so be careful of your wording. Write as precisely as possible, cutting down on descriptive words.

4. Zigzag reading pattern: The eye reads in a zigzag pattern, from top to bottom and left to right, so be cautious about emphasis and image placement to avoid the eye from going off of its normal reading track.

Chunk

The limitations of the brain and eye require that we "chunk" material on the page to aid in visual recognition. If we present the reader with too much information at once, the reader will probably not be excited to digest it all. If we chunk it, the reader is more likely to be receptive to what we have written. There are many ways to chunk (use short words, sentences, and paragraphs; headings; color; lists), the important thing is to do it.

Add White Space

Adding white space to a document gives the impression that the material can be read easily. This is a psychological effect on the reader and will result in a more usable document. Dense text on a page creates a gray appearance and reduces the ability of the reader to get through the material quickly. Opening up the document by adding white space draws the reader in and motivates them to read.

However, adding white space will increase the overall length of your document. Usually, the need for white space trumps the desire for a shorter document. If, however, the added white space will create a document that is too massive, you have only two options:

1. cram it all into one dense manual, or
2. split the material into two manuals with more white space.

Your decision will be based on the needs of your users.

Remember that too much white space can be just as bad as too little. Create a visually appealing balance by exercising restraint, discipline, and moderation.

Be Consistent
Forget the adage that "consistency is the hobgoblin of little minds." Be consistent in all aspects of your document design and writing. Consistency will reduce the effort needed by the reader to make sense of your document. Inconsistencies break the reader's rhythm--avoid this.

Team 4 (Chapman and Lukkonen)

Chapter 5 (Barker): Analyzing Your Users

2008-02-18T11:32:00.000-08:00

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

User Analysis Preparation and Planning

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

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

User Analysis

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

Tasks and activities the user will perform. “Learn the activities associated with his or her type of work.” [142] Look for tasks unique to the user’s workplace, tasks that require more than one software program and/or information from data resources, and tasks that require communication with other people.
User’s information needs. Expand the analysis into other work activities and roles users must participate. Find out what information the user needs, origin of information used (Internet, databases, trade magazines, etc.), and how the user communicates.
User’s work motivations. Try to tap into how software is used to help satisfy work motivations. According to Barker, “what motivates users professionally will also motivate them to do well with software—to assemble interface elements and basic operations into meaningful sequences leading to an objective.” [147] Tables 5.14 identifies sources of workplace motivation, and Table 5.15 suggests how to employ the motivational information in manuals.
Level of the user’s computer experience. Users bring a wide range of computer experience to each new program and so require different levels of support.

The novice computer user typically experiences anxiety with new technology and is generally distrustful of manuals. The novice user would prefer to be told what keys to press rather than self-exploration of the program.

Experienced users view software as a tool and have definite preferences as to how they want to learn new skills and programs. The experienced user understand the value of manuals and use online help systems more readily.

Expert users often work in the software industry, so they are confident with technology and can troubleshoot effectively. Expert users learn new programs easily but will consult a manual or online help.

Table 5.16 describes each of the three types of users and generalizations about documentation preferences of each type.
User’s knowledge of the program’s subject matter. The level of knowledge a user has about the subject matter of a program will determine how much background information to supply in the program. For instance, an accountant would probably need less background information for a tax program than the first-time tax preparer.
User community. Within organizations some type of official group (who Barker labels a community) forms whose purpose is to support software issues. User analysis should “investigate two things: the user groups that your users already participate in and your user’s willingness to join groups for mutual support.” [153] Examples of user communities include help forums, special interest groups, newsgroups, user groups, and web resources.
User’s learning preference. How does your user prefer to develop expertise with the new software? Generally, a user will learn with the help of an instructor, learn with the help of a manual, or learn through the computer. Consider how computer experience will determine learning mode. For instance, a novice computer user will more than likely prefer to be taught by an instructor rather than use a manual or computer assistance.
User’s usage pattern. “Usage pattern refers to the interaction of users with programs over time.” [164] In other words, how many features does a user learn or regularly use when using new software. Three main usage patterns exist: regular, intermittent, and casual usage. Knowing the usage pattern assists in developing better manuals and help.

Hood/Carlson

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

2008-02-18T06:18:00.000-08:00

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

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

The Final Solution: An Ethical Problem in Rhetoric

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

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

Ethics in Deliberative Discourse: Expediency

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

Hitler’s “Ethical” Program?

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

The Technological Ethos and Nazi Rhetoric

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

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

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

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

Final Question for Reader from Lance and Vanda:

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

Thank you for reading this summary! Lance and Vanda

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

2008-02-11T16:10:00.000-08:00

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Thanks for reading our chapter summary! Gary and Jennifer

What's Technical about Technical Writing

2008-02-10T22:58:00.000-08:00

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

Team 2: Gary Teagarden and Jennifer Bruns

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

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

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

Writing Technically

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

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

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

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

A New Definition of Technical Writing

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

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

Essay 9

2008-02-08T16:26:00.000-08:00

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Summary of Barker, Chapter 4

2008-02-08T13:55:00.000-08:00

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Access information
Function definition
Associated commands
Qualifications/special cases
Tips

Try to answer these questions for the reference user:

How do I get to the function?
What does the function do?
What other commands do I need to know about?
When can I use the function?
How do I use the function well?

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

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

(Submitted by Team 1: Beeman/Xiong)

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

2008-02-04T13:21:00.000-08:00

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

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

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

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

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

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

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

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

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

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

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

Barker, Chapter 3: Writing to Guide—Procedure

2008-02-01T17:13:00.000-08:00

Guidance information is also known as step-by-step instructions how-to instructions, or procedures, and makes up the heart of all task-oriented documentation systems. Procedures consist of a mix of explanations and steps; the job of the designer or writer of these is to balance these elements.

Guidelines

1. Relate the Task to Meaningful Workplace Activities

“A procedure is a step-by-step series of commands for accomplishing a meaningful operation with a software program” (p. 64). The goal of writing a procedure is to see it as a part of larger activities. Procedures are the operation part of the activity/action/operation model examined in Chapter 1. The job of the writer is to clarify how the procedures fit into the larger picture in the user’s workplace.

2. Determine How Much Information Your User Needs

How much information users will need depends on the difficulty of the task, and their experience. Identifying both of these aspects will help the writer decide whether to make the procedure richly detailed or sparse. Layering is “a formatting technique that allows for different levels of information (beginning and advanced) on the same page” (p. 87) and caters to both levels of users and levels of information.

To enrich procedures, consider adding the following:

· Screen shots (show the actual user interface, what menus to display, and what choices to make)

· Cautions and warnings (alerts user to be careful of damaging product, losing data, compromising performance of system, and possible harm to humans as a result of errors with software or equipment)

· Tips for efficient use (suggest alternatives, workaround, and helpful applications; can also elaborate a step or command)

· Tables showing options the user can take with a specific task (organize information and present it efficiently: features and uses, terms and definitions, setting names and options, users and program sections tables of contents; keep tables simple and cite them in the text; use descriptive, performance-based column titles)

· References to other sections of the manual or resources

· Explanations

· Cross-references and links

· Icons

· Graphics showing program concepts

· Keystroke combinations

· Examples

· Footnotes

3. Choose the Appropriate Procedural Format

Choose from standard, prose, or parallel; it is a good idea to stick to one.

· The standard format consists of steps, notes, screens, etc, aligned on the left margin.

Advantages: It is recognizable by users, there is an easy flow from one page to another, it is easy to renumber and test, and it is easy to see the steps using a hanging indent.

Disadvantages: It may occupy a lot of space and maybe confusing if complex and simple steps need to be mixed.

· The prose format includes steps in sentence and paragraph form; a conversational tone occurs in programs with simple tasks and a simple interface. Bold and italics are used for command verbs, function keys, buttons, and text for the user to type in.

Advantages: It is conversational and relaxed in tone, saves space, clarifies simple, basic steps, and accommodates experienced users.

Disadvantages: It buries the steps in paragraphs, precludes lengthy explanations of individual steps, can’t accommodate graphics for individual steps, and doesn’t offer much support for novice users.

· The parallel format is useful for programs that include complicated data fields or dialog boxes and programs that require the user to move from one field on a screen to another, filling in each one along the way. Writers and designers should keep the terminology consistent, cue terms to the screen, discuss one screen at a time, use plenty of examples, and explain to users how the format works.

Advantages: It can help users stay organized, works well with shorter procedures, and is good for filling out complicated screens and dialog boxes.

Disadvantages: It does not present information in a step-by-step, task-oriented manner, can’t be used for all procedures because it is specialized, may confuse the user who gets lost moving between steps and screens, and has to fit on one page.

· For embedded help, a writer working with a programmer put tags into both the program and the help system. It displays procedural information as a part of the interface of the system, and, unlike conventional help, is not a separate program. Embedded help is useful for tips for efficient use; cue cards; short, animated demonstrations; and trouble-shooting tips. Types of embedded help include flyout help, interactive flyout help, do it for me help, field-level help, interface help, pop-up definitions, and roll-overs (p. 79).

4. Follow a Rhythm of Exposition

This means a pattern of step, note, and illustration. First give a command for a step, then say how the program will respond, then illustrate what happened, then tell the next step.

5. Test All Procedures for Accuracy

Test the pacing and format for the desired effect. Perform evaluative tests, where an actual user or prototype of a user actually performs the steps.

Discussion

What Constitutes a Procedure?

“Procedures are often rooted in the features of the software program” (p. 81). But in the office or the business, these features can differ greatly from the uses. The writer or designer should consider the features as the tools the program provides for the user. The procedures result from putting the functions of the program into a usable set of steps that do the user’s work. Procedures usually follow a chronological sequence, with a beginning and an ending. Kinds of guidance information include installation (which is usually accompanied by a wizard, which is the personification of a guide or assistant), maintenance, and repair, but most procedures focus on the actual operation of the program, the day-to-day uses.

How Does a Procedure Work?

The task name identifies the program in performance-oriented language.

The overview serves first as an introduction and describes the use of the procedure. Using informal language, it should prepare the reader to perform the steps, by indicating necessary skills and conditions. Second, the overview directs the user once he or she is started with the procedure.

The steps give the user tools to use and actions to take with the tools. In writing steps, numbers should be used as opposed to bullets, and numbered steps should not include renumbered actions. In notes and explanations commands should be avoided and imperative verbs preferred.

Elaborations comment on the steps as they get performed. They can include possible mistakes and how to avoid them, how to perform procedures efficiently, alternatives (keystrokes, toolbars, function keys), definitions of terms, how to tell if a step was performed correctly, where to look for supplemental information. Elaborations should be phrased in an active voice and should refer to the program.

Options are optional commands or keystrokes and should be presented in a table.

Screens illustrate to the user the tool in use or the goal or results of an action. They can show an overview, a partial result, a final result, dialog boxes, toolbars, and menus.

Dianna Cowles, Robin Erickson, Anna Ignatjeva

Campbell: Chapter 3

2008-02-01T14:10:00.000-08:00

Isn't There a Law Somewhere?

This chapter covers the legal implications and considerations of writing policies and procedures.

Basic Overview

It is important to understand how statute and case law may affect your policies and procedures (P&P). It's not necessary to be a lawyer, but you should run any questions by your legal advisor.

You Can and Will Be Sued

Problems can occur when:

"Procedures used by customers or employees are unclear, imprecise, or poorly worded"
"Your policy or procedure violates some law or legal precept, intentionally or unintentionally"
"The wording of your P&P restricts the organization's ability to act"
"You have written P&P but don't use them or don't enforce them consistently"
"You fail to state who is responsible for or what the consequences of noncompliance are"
"Your policies or procedures are incomplete, in improper order, or inaccurate"

(Campbell, 58-59)

Some employees may have difficulty understanding your P&P due to language barriers or literacy problems. As the writer, you have a special obligation to help them understand, either by writing at an appropriate reading level or by offering translation.

Types of Violations

A tort, or an act that violates a law, can occur if your P&P violate safety regulations, fiduciary laws, fraud statues or public policy. Public policies are actions that may not be technically illegal, but "are recognized as being in the public interest."

Negligence is often more of a concern when writing procedures, where there are liability concerns or the possibility of injury or death due to poorly written operating procedures.

Breach of Implied Contract - Because P&P, whether written or verbal, can be considered an "implied contract", violating them can leave you open to prosecution for breach of implied contract. These cases often involve disciplinary or termination matters.

Disclaimers

Disclaimers can offer some protection. For example, a handbook or manual might contain a disclaimer that states that the "contents may change and are not contractual."

Manuals vs. Handbooks

The difference between the calling something a manual or a handbook may seem insignificant. However, from a legal standpoint, a "handbook" is often considered to be more widely distributed than a manual, which may imply that it can be considered contractual. The term "user's guide" implies that the contents contain guidelines; it is being used more often since the term avoids the appearance of making promises or implying contracts.

What the Courts Want You to Do

Businesses are expected to "operate in a safe, reasonable, and fair manner." They are expected to clearly communicate and enforce the P&P.

How to Protect Yourself

To avoid lawsuits, it is important that the P&P are well written, understandable, and accurate. They must follow laws and regulations and should contain disclaimers and words that express management's right to make changes and take alternative action, if necessary. The rules for noncompliance should be articulated and followed consistently. Informal and written rules should also be considered.

Other issues:

You can be accountable in a court of law for Informal and unwritten rules.
Old, outdated P&P can still get you in trouble. It's important to keep your P&P updated.

2008-01-29T09:50:00.001-08:00

Robert Connors: The Rise of Technical Writing Instruction In America

2008-01-27T22:58:00.000-08:00

I. The Early Years: 1895-1939

Robert Connors’ article on the history of technical writing instruction was published in the Journal of Technical Writing and Communication in 1982. It is an extensive narrative on the progression of technical communication, with an emphasis on academia.

Connors writes that technical discourse has existed ever since the use of tools and man’s communication about them. Technical writing can be traced historically back to the Sumerians and Roman Empire. Systematic instruction of technical writing, however, is still a rather recent development. Connors’ article is an attempt to trace instruction in technical writing from its beginnings to its present state.

Engineering Education in the Nineteenth Century

Technical writing courses have been taught in American colleges since the late nineteenth century; however, the first courses were sparse. The Morrill Acts in 1862 and 1877 “founded and promoted the land-grant agricultural and mechanical colleges that were to make college education available in the later nineteenth century to a hugely increased percentage of the population” (4).

Studies in math, modern languages and literature, liberal arts, and more were added to college curriculum alongside Greek and Roman philosophy and literature. The Civil War made way for this change as engineers were seen as important figures, and the Industrial Revolution meant that schools of engineering were a part of natural progression.

Still, upper-level writing courses were rare in the nineteenth century. Before 1870 an engineer would graduate with little education in writing. In fact, many engineering schools at the time dropped humanities courses almost completely. What remained was the basic of all writing courses—freshman composition. It was believed that taking freshman composition would be enough for engineer to get by.

Engineering education became more sophisticated as the nineteenth century was ending, but it still did not place emphasis on the linguistic needs of its students. “The Society for the Promotion of Engineering Education (SPEE) was founded in 1894, but it had no members from English departments until after 1905, and in general, engineering schools acted as if their students needed none but technical courses” (5).

At the start of the twentieth century, articles condemning the illiteracy of engineering students began to appear in engineering articles. It wasn’t hard to see why this controversy started. Freshman composition courses were simply too general. On top of that, J. Martin Telleen explained in 1908 that freshman English courses came too early in their careers. He also noted that English and engineering faculties rarely engaged in interdepartmental cooperation.

Samuel Earle and Early Technical Writing Theory

“The period 1900 through 1910 was the gestation period for technical writing courses” (6). Some engineering schools actually created English departments to serve the special needs of students.
T. A. Rickard’s A Guide to Technical Writing (1908) became the first important textbook on technical writing. It dealt mostly with usage, and while it was used for college classes, it was more meaningful to practicing engineers. In 1911, the “first genuine technical writing textbook written for use in college courses,” (6) was published. The book, called The Theory and Practice of Technical Writing, was authored by Samuel Chandler Earle.

The Theory and Practice shared few elements with composition texts of the early twentieth century. “It grew out of courses in ‘engineering English’ that Earle had been teaching since 1904, courses that were perhaps the first recognizable technical writing courses” (6). Earle became the philosophical voice of the early technical writing movement. He defended his position on general composition, stating that it was not enough for engineering students.

Earle also commented on the division between English and engineering teachers, stating that the sour attitudes between the two were immature and misguided. His idea was that continuing education in other subjects to further one’s career shows true devotion.

Earle’s influence on the education of teaching English in engineering school was monumental. The decade that followed his death saw great improvement in the growth of technical communication. “Between 1911 and 1920, the basic elements of technical writing courses as we now teach them were limned out at a number of schools around the country” (7).

Complaints about technical school graduates were prevalent by 1916, but engineering schools attempted to change that. A demand arouse, asking for a basic literacy in engineering graduates. Unfortunately, English teachers often used their own methods, and students ended up being taught literature along with writing. This resulted in a problem in understanding between English and engineering faculties.

“On the east coast there grew up a movement led by Frank Aydelotte of MIT whose aim was frankly to ‘humanize the engineering student’s character and his aims in life’ through literary study” (7). He stated that engineers should be able to write what they practice. Some schools taught English courses inhouse where faculty in both English and engineering worked closely together.

“During this period there were generally three sorts of English courses available for engineering students: the required freshman composition course, a sophomore literature sequence that was sometimes required, and the junior- or senior-level courses in ‘exposition for engineers’ that were the prototypes of today’s technical writing” (7). Problems arose immediately, though. Many students were not interested in learning to write or read, English teachers were often young and inexperienced, and the cooperation continued to lack between engineering and English departments.

The Formation of a Discipline

“Prior to 1912, there had only been two English teachers in the SPEE, but seven more joined that year… The Mann Report on Engineering Curricula in 1918 recommended more time spent on English, and by 1920, 64 percent of all engineering schools required some sort of technical writing course for their students” (8). At this point, engineering-only hardliners gave in and fit English into the curriculum.

At the start of the twenties, the amount of time devoted to technical writing increased, new courses were suggested, and new textbooks began to appear.

The first “modern” technical writing textbook was distributed in 1923 (English for Engineers). It was written by Sada A Harbarger of Ohio State University. The book is organized by “technical forms,” and this still remains the basis for most textbook organization.

Two new developments in technical writing—practical and philosophical—came about in the mid-twenties. The practical development focused on the writing of technical reports, and the philosophical development began to focus less on literature.

“A 1924 SPEE survey found that it was no longer necessary to urge the importance English for engineers… The survey also found that English requirements at engineering schools had doubled since 1914 and that more colleges were instituting technical writing courses each year” (9). At this point it became clear that English found a place in engineering education.

Expansion and Depression

Changes continued throughout the twenties: new textbooks appeared, and technical writing courses refined themselves slowly but stuck to relatively rigid forms.
“Another SPEE survey, in 1930, showed that of 1300 engineers and teachers, 95 percent approved requirements in English composition, 75 percent approved speech requirements and 45 percent approved literature requirements” (9).

The Depression during the early thirties hit engineering schools hard, and engineering teachers still did not give English teachers proper cooperation. English teachers were accused as being insufficient in teaching students. Regardless, technical writing courses continued to fill. Every year, more classes opened and new textbooks sold well.

A dissertation (later turned into a published report) by Alvin M. Fountain appeared in 1938, and the results of its survey/interviews “showed that of 117 engineering schools in America, 76 schools offered 93 different technical writing courses in 1937” (10). This report detailed course content, textbook use, and teaching methods. “The most important information… is that he shows how a technical-forms approach of a rigid and mechanical sort had become all but absolute by the late thirties” (10). The report clearly showed that technical writing was thriving. On the other side, though, the report had also shown that the teaching of technical writing had seen little progress, and the gap between engineer and English teachers widened.

II. A Discipline Comes of Age: 1940-1980

Developments During World War II

During World War II, it appeared that engineering English articles had ceased; however, the teaching of technical writing continued despite lower enrollments.

Two SPEE reports had no immediate effect, but later would “change the course of post war engineering education in America” (11). The Hammond Reports of 1940 and 1944 encouraged a mixture of humanities and sciences at four-year schools. The suggested program would be to have 20 percent or more of the student’s time devoted to humanities. By the early fifties, the “humanistic-stem proponents had achieved final victory” (11).

The Postwar Technical Writing Room

Technical writing courses continued to expand, especially after the war. Part of this had to do with students attending on the GI Bill. Another reason for expansion was due to the nature of the war—it was a technological war. Technical writers were needed to write manuals for airplanes, guns, bombs, and other machines. Technical writing became a job instead of a function.

After the war, technical writing became a profession as technological corporations opened divisions for technical writers—they realized that it was less cost-effective for engineers to design and write. Still, at this point, technical writing was not a major offered at colleges. Courses in the postwar era saw a rise in demand, and teachers tried to cope.

The late forties saw a greater expansion in the number of forms taught in technical writing courses; only gradually had business letters been added. By 1951, six different report forms were widely taught, and more than ten letter types were eventually taught. Manual writing also became popular, partially due to military influence, but also due to “the increasing number of technically-based consumer products American was turning out” (13).

A New Professionalism

The 1950s led way to the essential form of technical writing as we know it today. The Society of Technical Writers was established in 1958. The fifties also saw the industry’s taking notice of technical writing as a profession, and colleges gave serious consideration to technical writing as a standalone major. In 1958, Rensselaer Polytechnic Institute established the first master’s degree in technical and scientific writing in the United States.

Most campus technical writing programs were still plagued by the usual problems, but courses continued to be refined. The humanities requirements that were proposed in the Hammond Reports were beginning to be replaced by technical writing requirements. “By 1957, nearly all colleges offered a technical writing course, and 64 percent of engineering schools made such a course a requirement during the junior or senior year” (13). Required courses were more carefully constructed than past courses, and experimental teaching methods became more common. Most successful courses came from cooperative courses team-taught by English and engineering teachers.

“Mills and Walter conducted a survey of over 300 actual technical writing situations in industry, and from this survey came a number of changes in the approach that informed their textbook” (13). Two important assumptions had gleaned from their survey were

A rhetorical approach rather than the rigid “types of reports” approach that most texts used was best. Most reports are made up of several common processes: definition, description, explanation of process, etc.
The only good criterion for technical writing is “does it work?” This indicates that in technical writing as well as in other rhetorical forms, the writer-reader relationship is most important. (13)

Mills and Walter’s “Technical Writing reflected these assumptions and went on to be the most popular and paradigmatic text of the fifties, pointing the way to a new rhetorical approach to technical writing that was to revivify what had been in danger of becoming a sterile and mechanical course” (13-14).

Others also agreed that a reader-writer relationship was crucial in technical writing instruction. “A growing awareness that audience considerations had long been scanted in technical writing was one of the important developments of the 1950’s” (14). Critics condemned technical writing courses in 1955 for their dismissal of audience consideration.

The fifties also saw the expansion of technical writing into fields other than engineering. Departments such as agriculture, architecture, chemistry, pharmacy, and home economics pushed their students toward technical writing. The course was seen as a viable addition to the curriculum. Courses also evolved to include additional assignments and materials.

Breakthroughs and Problems

By 1959, technical writing textbooks were high in number. By the end of the fifties, textbooks replicated the rhetorical approach of Mills and Walter. Despite the long and honorable history, technical writing received little welcome from literary departments.

America began a war of technology with Russia after Sputnik was launched in 1957, and as the sixties opened there was a serious shortage of technical writers in the industry. Industries engaged in bidding wars for the few technical writers. The Society of Technical Writers changed to the Society for Technical Communication, and it still thrives today. “As a group, technical writers advanced greatly in both pay and prestige” (14).

College campuses still saw problems, however. Courses struggled to define themselves, teachers were unsure what to expect in their jobs, and students were getting more intelligent but were fewer in number as the sixties proceeded.

“Robert Hays investigated the nature of technical writing in 1961 in a widely reprinted essay entitled What Is Technical Writing?” (15) W. Earl Britton wrote the most comprehensive early definition of technical writing by defining it by subject matter, linguistic nature, thought process involved, and purpose. “Britton’s conclusion was that technical writing is defined more than anything else by ‘the effort of the author to convey one meaning and only one meaning in what he says’” (15).

This paved way for an awakened interest in the sixties. The first steps of empirical research into technical writing and the teaching of it were made. Researchers gathered and analyzed facts about technical writing in a scientific manner.

Despite this growth, the same old problems still existed with courses. Teachers continued to battle over whether to teach technical students to write or read and appreciate literature. In the sixties, technical writing teachers continued to be graduate students and low-level faculty members. Literary studies continued to be the interest of many technical writing teachers well into the seventies.

A major form emerged in the teaching of technical writing emerged in the sixties: the proposal. “During the late fifties and early sixties, it was estimated that industry spent in excess of one billion dollars per year on the writing of proposals, and the importance of this new form soon became obvious to the writers of technical writing texts” (16). The first textbook to tackle proposals was published in 1962: Siegfried Mandel and David L. Caldwell’s Proposal and Inquiry Writing. It was received well, and the proposal as a form soon spread to all texts.

Retrenchment and a New Sense of Identity

Well into the early seventies, a serious drop of students enrolled in engineering programs occurred, even though general enrollments were on a steep rise. Enrollments in technical writing courses shrank as well.

Despite the decrease, dedicated technical writing professionals teamed, and in 1970 “the Journal of Technical Writing and Communication was started, a journal which quickly became the most respected organ in the field of technical writing instruction” (16). The journal exclaimed the interests and tools of technical writers. “Tools became more sophisticated; in 1971 Stello Jordan and his associates published a two-volume Handbook of Technical Writing Practices” (16), which was considered the most sophisticated and complete technical writing guide ever published.
In 1974, technical enrollments began to rise again, and by the late seventies they went up an average of 10 percent per year (when college enrollments were becoming static). “The Modern Language Association, which had for over fifty years refused to recognize technical writing as a legitimate function of English scholars caved in during the midseventies and gave technical writing belated recognition in 1976” (16).

The demand was simply a result of the continuing need for technical communicators in industry. “A survey during the late seventies showed that over 50 percent of an engineer’s time was spent dealing with writing, and over 85 percent of professional engineers polled said that a technical writing course should be required of all technical students” (16). More departments continued to require a technical writing course. Teachers were not always rewarded, but many gained credit that had previously been nonexistent. Courses were filled, and many teachers found additional opportunities in consulting for industry, and consulting would help to improve in-class instruction. Available positions also became more and more available, and the seventies proved to be a good decade for technical writers.

Textbooks became more sophisticated and were made available for two and four-year colleges.
At the end of Connors’ article, he states that technical writing should be taken out of the hands of English teachers. It is interesting to note that at Minnesota State, our technical writing program is listed in the English department. As Connors would see, the instructors here do understand the separation of literature and technical writing, so he would most likely be pleased.

This article was not easy to summarize (as you can tell by this summary’s length). The amount of information that Connors wrote was concise, with every sentence containing a new thought. We thank you for your time in reading this summary!

Team 3 (Lori Hood and J.J. Carlson)

Barker, Chapter 2: Writing to Teach — Tutorials

2008-01-25T05:33:00.000-08:00

Tutorials are designed to teach how to use something, such as new software. It may teach a beginner focused lessons on starting out, or it may teach an advanced user more complex focused lessons. Tutorials, like other software documentation, should be created with the user in mind.

Guidelines

There are seven recommended guidelines to follow for tutorial design:

1. Identify User Actions You Need to Support

Analyze the users of the program and their needs, including what they use on the job, what software features are essential, and what features are used frequently. Embedded tutorials are useful to detect important skill lessons, but it should be clear how to close the embedded tutorial if not needed.

2. State Objectives as Real-World Performance

The objectives of the tutorial should be stated in the module in terms of the user's performance. State exactly what will be learned in measurable terms.

3. Choose the Right Type of Tutorial

Types of tutorials include The Guided Tour, The Demonstration, The Quick Start, The Guided Exploration, and The Instruction Manual. The Guided Tour consists of an overview of the main features of a program. It can be online or in print. The Demonstration demonstrates specific actions in a program. Experienced users may use The Quick Start to jump right in to a program and start working with it. The Guided Exploration allows the user to determine the direction of the tutorial, exploring its options. Finally, The Instruction Manual teaches users step by step how to use a program, from basic features to more advanced ones.

4. Present Skills in a Logical, Cumulative Structure

It is not enough to prepare logical and organized lessons in your tutorials--you must also order those lessons in a logical and coherent way. Like other aspects of documentation, the proper order and structure will be determined through an evaluation of your user's needs, i.e., a typical-use scenario. Usually, the tutorial will progress from the general to the specific, the structure of which will mirror the typical user's workplace routine.

5. Offer Highly Specific Instructions

Instructions should emphasize scenarios that are familiar and applicable to the user. These scenarios should contain specific instructions to ground the user in the lesson. Keeping them grounded will help them fight feelings of insecurity they may be having toward having to master a new tool. Some examples of specific instructions include using concrete data, interface tools, screens, and specific commands. In addition, remove all distractions from the lesson, including page design elements that may interfere with the learning process.

6. Give Practice and Feedback at Each Skill Level

Giving users positive feedback in a conversational and positive manner will help orient them emotionally to the tool you are helping them learn and to the tutorial itself. Avoiding jargon and making liberal use of "you" and "we" will give the tutorial a "human touch."

Building consistent patterns gives predictability to the tutorial and reduces the amount of work the user must go through to understand the concepts that are being taught. Avoid alternative explanations because they may overwhelm some users and distract them from what they are learning. If feasible, build in practice exercises or quizzes into the tutorial to help keep the interest of adults who enjoy challenges and self-exploration.

Because most of your users will have competing demands on their time, keep the lessons short, about 10 to 12 minutes each. Also, let them know how to save their progress in case they need to shut the tutorial down and pick up where they left off at a later time.

7. Test Your Tutorial

Usability testing gives you necessary information about the effectiveness of your tutorial. If possible, test the tutorial in a real user environment. Focus the testing on the design elements, such as the cuing system and graphics. Perhaps most important, ensure that users can complete the lessons in the allotted time and that the lessons result in real learning.

Designing Tutorials

Because tutorials are designed to teach, the tone of the writer's persona must match the intended user to create a close relationship between the two. Because the goal of tutorials is to internalize work-related tasks and concepts, try to limit the scope of what the user is exposed to. This contrasts with other forms of documentation in which the writer attempts to be as expansive as possible. In order to narrow the scope of the tutorial appropriately, you must fully understand the needs of the user--which tasks are essential to them and which aren't? Without a thorough user analysis, it is impossible to narrow the scope of the tutorial appropriately.

Tutorial Users Need Special Care

Most of your users will be adults who have their own motivations for wanting to learn the tool that your tutorial is helping them master. For your tutorial to help them successfully, you must take into account the varied learning styles of your target population. As a tutorial designer, you need to understand how to limit the lesson times, prevent the user from being publicly humiliated for mistakes they make, give positive feedback, and make the user feel that they are self-directing their own learning.

Two Trends in Tutorial Design: Elaborative and Minimalist

The elaborative approach to tutorial design emphasizes reiteration to "bring the message home" to the user. Summaries, examples, and explanations all reiterate the learned material and may help the user retain and apply the knowledge they have gained. This approach is especially important for novice users with little-to-no experience with computers or the program being taught.The minimalist approach gives a nod to real human behavior: people often want to get off and running, without spending a lot of time in advance preparation. In the minimalist approach, the introductions and summaries are discarded because most readers will skip them anyway. To create effective minimalist documentation, use an action-oriented approach that is grounded in a workplace context that helps users recover from errors made and supports reading to "do, study, and locate."

Team 4 (Chapman and Lukkonen)

Campbell, Chapter 2: Where Do I Start?

2008-01-24T21:25:00.000-08:00

In policies and procedures writing, we talk about the development process instead of the planning process. It’s important to develop the project instead of diving into writing, because if we immediately start writing, we may be missing something crucial to the project.

The four steps of development are

Planning
Analysis
Research
Prewriting

Each step should be covered, if even briefly, and all should be done in order. Outlining is not recommended because it wastes time and could cause errors.

Step 1: Planning

A plan, in most cases, should be written
This step is not always formal

Since every project has a deadline, a plan should be kept somewhat simple. For this, it is a good idea to plan the basics:

Tasks
Sequence
Deadlines

Set a schedule

List the steps
Indicate team member responsibilities
Make timetable estimates

A team’s size is important because too much work for few writers will make it difficult for the team to meet the deadline. Our text states the following when working with a team of writers:

Select members with appropriate backgrounds or expertise
Meet or talk regularly
Establish ground rules
Agree on assignments and responsibilities
Establish a monitoring system
Agree on deadlines
Develop a team style guide

Be realistic: Make sure the plan is doable, and always check for conflicts and other possible concerns (such as other projects that have their own deadlines). A written plan should help address these possible road blocks.

Step 2: Analysis

In this step, the team should look at the project’s

audience
assignment
context
relevant research
conditions for the work

Some concerns can be answered in analysis through the following:

Look at who requested the project, and why the requested it. What led to the project’s conception? To what degree is the nature of the project? Is it technical or non-technical? Simple or complex?
Know your goals. What do you want to result from the project? If you’re ever unsure, ask for more information (from knowledgeable sources such as the requestor).
Know your audience so you can mold the document for them. What are their experience levels, interests, preferences, attitudes, and so on? How will they use the document?
Know the project’s subject matter and its urgency. How big of an impact will it have on the organization? What are the conditions you will be working under?
Go over important concerns with the requestor of the project. In this manner, update them regularly.

Step 3: Research

First action here should be on matters of content.
The amount of research here should be determined on what was found relevant in step 2.
Ultimately, you will determine the amount of research.

Start with the most difficult research first as it will probably take the most time. This will give you time to ask questions and get clarification.

If it is possible, get information from experts who know the information you’re searching for. Also, talk with anyone who could provide input (such as the users of your document).

Relevant material should be read (books, articles, organizational files, etc.). And, of course, concentrate on critical information over anything else.

Step 4: Prewriting

Prewriting involves organizing the material, and this helps to speed drafting. This step is done before writing, and it is recommended to hold off writing at this point. An important question here is, “How do I convey this information to the reader in the clearest, most logical way possible?”

Content is key, so make sure all necessary information is gathered. The book suggests to practice mind-mapping (see example 2-8, p. 55) to gather and organize data. Mind-mapping reverses the process of outlining and allows you to focus on content issues first:

It removes our creative side and brings all content to the forefront of organization.
It helps you record your thoughts and knowledge at random.
It is less likely that important information will be omitted.
It may be easy to do, but it gets results.

Finally, in prewriting, you should develop a flow or sequence of the material that would be most logical to the reader. Will the reader use the information in a way that works for them and the organization?

Thank you, everyone, for participating in discussion on this chapter!

Team 3 (Lori Hood and J.J. Carlson)

Campbell, Chapter 1: What's a Policy, What's a Procedure?

2008-01-18T11:49:00.000-08:00

What’s a Policy, What’s a Procedure?

You need policies and procedures because otherwise there would be chaos and frustration. Policies and procedures are the way an organization operates. Policies deal with the “what” and “why” while procedures deal with the “how.”

Policies are guidelines that regulate organizational action. Policies are used to explain an organization’s view on a certain subject or issue and why their view is what it is. Policies are up to each organization to decipher and regulate as long as their choices do not break any laws. Decision-making is the key in policy making, because if the organization doesn’t know what direction it wants to go in, the employees lose sight of what is important to the company and this can result in lost productivity and job loss due to the lack of clear direction.

Policies can be either ambiguous or specific, depending on the subject matter. It is up to the policy writer to determine when it is appropriate to be ambiguous and when more specificity is needed for certain policies.

Procedures are the normal method of handling things. Procedures tell employees how to go about their daily job in an appropriate and safe manner. Procedures are action oriented and can point out the consequences of not following procedures correctly. Procedures should be very specific, and oftentimes can be regulated by safety organizations such as OSHA, and will help employees to stay safe and in good standing while on the job.

Policies and procedures can be difficult to write because they require both an air of subjectivity and an assumption that the employee will take their own actions and position within the organization seriously and with regard to others on the job.

Policies and procedures should be carefully considered before they become “law.” They are not always appropriate, and they can sometimes lead to employees feeling micromanaged or result in more incidents because employees got “bored” reading through all the procedures and therefore didn’t. Be sure that the organization goals are clearly communicated, and employees will generally try to fit within those goals.

Written vs. Unwritten

Unwritten rules can sometimes be more preferred than written rules. We all have unwritten rules, whether we realize them or not, that come into our daily lives and work lives all the time. It is best to leave a policy or procedure unwritten when:

· It involves organizational culture and norms,

· It cannot be consistently enforced,

· It is potentially offensive or intrusive, or

· It simplifies another rule that employees already understand.

Sometimes, these unwritten rules DO need to be written down, but unless something serious has happened such as an accident or a complete disregard for even the ambiguity of the unwritten rule, unwritten rules are normal and almost expected in organizations.

What to Include in Policies and Procedures

It can be very hard to know what needs to be included in policies and procedures, especially when there are the aspects of keeping the rules ambiguous at certain times and specific at other times, or when there can be rules that do need to be written and those that do not. The audience is the key in determining what needs to be in your policy or procedure. Purpose is another big determiner in what is written. Writers need to determine what readers need to know as opposed to what they want to know. It is important to ask who wants readers to know specific policies or procedures, and if the writer can answer that question, it can be assumed that the policy or procedure NEEDS to be included. If information is interesting, but maybe not necessary, to the employee, that is information that they will WANT to know. Writers need to keep in mind that the readers of policies and procedures want to know what’s in it for them (WIIFT) – what it will mean to them and for them.

Discretion is key in determining the detail content of the policy or procedure. If a subject or topic is complex, or if the policy or procedure contains a legal aspect, the policy should be as detailed as possible to avoid questions or misinterpretations of the rule. Writers should be sure to do a thorough audience analysis before writing or updating policies because that is who the policies and procedures are directed at, and can help the writer to determine what level of detail is appropriate.

Manual or Handbook?

Once an organization has its policies and procedures written down, it is important to organize them into one place where employees will know where to go to find the information when they need to reference it. Many institutions call these organized books of information either manuals or handbooks. There are legal connotations associated with both of these terms:

· Manuals imply restricted circulation within an organization, and

· Handbooks imply general distribution.

If a writer is concerned at any point about a contractual issue, it is important to know the differences between the two as they could create legal troubles later.

Summary by Team 1: Amy Beeman and Jane Xiong

Barker, Chapter 1: "Understanding Task Orientation"

2008-01-17T12:21:00.000-08:00

Introduction. This chapter helps writers achieve two goals: encourage users to learn the program and to apply the program to the workplace. The chapter also defines task orientation, the nine characteristics of manuals, the five characteristics of the default user manual, and the five characteristics of the task-orientated user manual.

But before we begin, what is task-orientated documentation? Task-orientated documentation is really the challenge of creating documentation that looks at the process of writing and finds ways to learn about users. Task-orientated documentation consists of manuals and help that reflect real users and human forms. The process of task-orientated documentation requires that you analyze the user in his or her work environment to discover the rich texture of activities within the software program and where the manual fits. Barker's goal is for us to write task-orientated documentation with the manual's user in mind. This book has the technical communicators goal in mind--to be an advocate for our readers!

Barker talks of “actions” and “operations” when explaining the computer user’s environment. “Actions are tasks that grow out of work situations that often require communication and thought.” In other words, actions have a goal and purpose, such as producing an easy-to-read annual report. On the other hand, operation-centric documentation teaches one narrowly focused commands, such as the menu functions on a program. (e.g. “save to disk,” “spell check,” etc.) The thorough exploration of both, actions and operations is essential to task-oriented documentation.

CHAPTER OVERVIEW

GUIDELINES All software documentation should explain and show connections between the user's work and the computer program. Barker's book will explore different techniques that will help us write a manual.

Here are some of the techniques we will learn more about in coming chapters:

Emphasize Problem Solving: help users solve problems in the workplace.
Provide Task-Oriented Organization: organize our manuals in such a way that it will match the tasks that the user will need it for.
Encourage User Control of Information: write the manual in such a way that the user decides what the software program will do for them.
Orient Pages Semantically: this is a design that arranges the elements of the page meaningfully, according to the elements of the functions the user needs to perform (i.e. putting important elements first).
Facilitate Both Routine and Complex Tasks: the documentation should include repeatable tasks (routine tasks) and tasks that require the user to apply knowledge that isn't easily codified in step-by-step procedures (complex tasks).
Design for Users: the organization reflects the user's needs.
Facilitate Communication Tasks: the manual requires users of the software to communicate about their work (this means the documentation depends more on the workplace demands of the user than just on the software features).
Encourage User Communities: task-orientated documentation encourages users to identify and get help from users, usually those in their user group.
Support Cognitive Processing: the documentation uses principles of knowledge representation, parallelism and analogy to convey software features and applications to workplace tasks.

DISCUSSION Principles of software documentation. Barker's book addresses a need for the business and the professional workplace to use software efficiently and effectively. The software user has two goals: the goal of learning a program and applying the program. We have to convey the correct instructions on learning to use the program, helping users navigate menus, learn commands, and terminology of a program. Therefore, our goals as technical communicators are to teach the features of the program and tell how to apply the program to complex tasks.

A definition of task orientation. Barker defines task orientation as: a design strategy for software documentation that attempts to increase user knowledge of and application of a program by integrating the software with the user's work environment. Our manual should increase job efficiency, not hinder it.

Theory behind task orientation. There are two ways to define the user of any software, as a person who needs to learn about menu functions and commands, and as a person who uses the software for workplace ends (this is our main goal). Barker categorizes these two users as the default user and the task-orientated user. Let's explore these with more depth... (just as a note, Barker explains each bullet point in his first chapter.

Default user:

Perceives job skills as decreasing in importance
sees computer use as separate from job goals
becomes isolated from other employees
fears remote supervision
suffers from information overload

Task-oriented user:

challenged by redefined work activities
conceptually orientated
aware of user communities
self-managing
supplied with resources

We want to shape our software documentation and aim it towards the task-oriented user. We want our documentation, therefore, to be task-oriented. :)

The forms of software documentation. There are different types of documentation users. Users use manuals for different tasks, including: planning tasks, decision-making tasks, problem-solving tasks, operating tasks, and knowledge tasks (please see Table 1.6 on page 19 for more information). When we create our manuals we need to look at how people are using the software and how they are applying the program to their work. Users first often learn how to apply the program to their work, how the features match their workplace goals, and how the actions they perform correlate to the menus and the screens. Next they use the program on a daily basis and sometimes more, and then finally users become advanced so that they just need to look up information about a program or troubleshoot error messages.

Three manuals can be created for each type of user:

Tutorial documentation: intends to teach the basic functions and features of a program to a person can begin applying the program to workplace tasks. Examples: getting started guides and online tutorials.
Procedural documentation: intends to guide the user in everyday use of the program, often when the users need information at the time of user. Example: step-by-step procedures.
Reference documentation: intends to supply information "about" the program to advanced users that rarely consult the user's guide or tutorial but occasionally need to look up information about the program. Example: alphabetical listings of program features, lists of examples, file formats.

The processes of software documentation. It really begins by exploring what users are using the software for; again, taking that human approach. This is a process of exploring user needs and then of constant involvement of the user in the process of writing and testing (this process is called usability process). Users and their needs drive the writing. Please see Figure 1.8 for the different stages of writing software documentation, which include the planning, development, and evaluation stages.

Finally, Barker concludes “A manual that integrates a software program into the user’s environment has a better chance of getting used than a manual that only documents the features of the program.” Words of wisdom for all of us.

Thank you for reading our chapter summary!

Jennifer and Gary

Welcome to our course blog

2008-01-11T09:45:00.000-08:00

We will use this blog to discuss our course readings for the semester. Welcome!