Barker Chapter 7

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

Getting Useful Reviews

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

1. Review the document objectives from the documentation plan
2. Determine the type of review needed
3. Establish a review schedule
4. Plan the reviews
5. Write a cover letter with questions for reviewers
6. Prepare feedback material for reviewers

Review the document objectives from the document plan:

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

Determine the type of review needed:

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

Establish a Review Schedule:

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

• Low cost
• Less hassle
• Encourages team spirit
  

Cons:

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

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

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

Cons:

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

Plan your reviews:

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

Write a cover letter with questions for the reviewers:

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

Prepare feedback materials for reviewers:

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

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

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

Nancy J. Campbell

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

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

What to Put in a Manual or Handbook

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

What Users Want

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

How to Give It to Them

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

The Design Elements

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

Table of Contents

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

List of Illustrations

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

List of Forms

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

Introduction

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

Glossary

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

Appendix

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

Index

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

The Production Elements

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

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

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

Size

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

Paper

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

Color

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

Binders

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

Cover

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

Dividers

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

Distribution Issues

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

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

The Shape of Text to Come

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

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

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

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

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

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

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

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

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

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

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

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

Johndan Johnson-Ellias


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