Barriers and Approaches to Reviewing Documentation

This article discusses some important issues in implementing a software documentation review process. If you are part of a small development organization and have few reviewer resources available, you may have to improvise techniques for providing the services and procedures suggested here.

Boston Broadside (1997). Articles>Documentation>Editing>Collaboration

Beyond Copy-Editing: The Editor-Writer Relationship

Editing is often narrowly defined as making corrections after a document is written. This approach typically relegates the editor to a low-status role within the organisation.

Durham, Marsha. Technical Editors Eyrie (1991). Articles>Editing>Collaboration

Creating an Editing Policy  

As an editor, you realize how important it is to edit information consistently. What you might not realize how important it is to let the writer know how you are going to edit, what you are going to edit, and what you expect from the writer. An editing policy lets you communicate these things to the writer. When you and the writer know what to expect from each other, you are able to work together as a team to produce a quality document.

Reed, Wendy L. STC Proceedings (1994). Articles>Editing>Collaboration

Creating, Implementing, and Maintaining Corporate Style Guides in an Age of Technology    

This article details a step-by-step process for creating, implementing, and maintaining a corporate style guide to ensure consistency in organizational communication. Through literature research, analysis of sample style guides, and practitioner interviews, this article provides recommendations for gaining management support, building a process to develop a style guide, determining content, encouraging employee buy-in, and maintaining a corporate style guide.

Bright, Mark R. Technical Communication Online (2005). Articles>Editing>Style Guides>Collaboration

Critiquing Critiques: A Genre Analysis of Feedback Across Novice to Expert Design Studios    

In the discipline of design, the most common presentation genre is the critique, and the most central aspect of this genre is the feedback. Using a qualitative framework, this article identifies a typology of feedback, compares the frequencies of feedback types between different levels of design studios ranging from novice to expert, and explores what the feedback reflects about the social and educational context of these design studios. Results suggest that the feedback socialized students into egalitarian relationships and autonomous decision-making identities that were perhaps more reflective of academic developmental stages or idealized workplace contexts than of actual professional settings--therefore potentially complicating the preprofessional goals of the critique.

Dannels, Deanna P. and Kelly Norris Martin. Journal of Business and Technical Communication (2008). Articles>Editing>Collaboration

Editing a Moving Target

I'd like to assume that most of us find ourselves having to edit a moving target only occasionally, but from the horror stories I've been hearing, it seems that more and more people are being expected to edit well in a ridiculously short time.

Stoughton, Mary. Editorial Eye, The (1997). Articles>Editing>Collaboration

Factors in Reader Responses to Negative Letters: Experimental Evidence for Changing What We Teach    

This article summarizes the scholarly discussion about negative messages and reports the results of two pretests and two experiments using negative letters. The results show that buffers did not significantly affect college students' responses to simulated letters refusing credit and denying admission to graduate school, and strong resale was counterproductive. Students responded least favorably to rejection when they were surprised by it and when their other options were limited. On the basis of these experiments and the published literature, the author recommends that negative letters normally begin with the reason for the refusal, using a buffer only if one of several exceptions apply. If the reason makes the company look good, it should be spelled out in as much detail as possible. If an alternative or compromise exists, the writer should suggest it. Although a positive ending is not necessary, if one is used, a bland positive is better than a strong one, especially in letters to clients or customers.

Locker, Kitty O. Journal of Business and Technical Communication (1999). Articles>Editing>Collaboration

Flexible Diff-ing in a Collaborative Writing System  

Discusses the use of computer-generated information about what has been revised in the display of editing in word processors.

Neuwirth, Christine M., Ravinder Chandhok, David S. Kaufer, Paul Erion, James Morris and Dale Miller. Computer Supported Cooperative Work (1992). Articles>Editing>Word Processing>Collaboration

Getting Reviewers to Review  

Presents ten humorous suggestions for technical writers on how to persuade reviewers of documentation to do their jobs.

Hart, Geoffrey J.S. Intercom (2000). Articles>Editing>Collaboration

The Knowledge Editor(SM): Innovative Editorial Solutions to Meet Your Quality Objectives  

This paper represents over 30 years cumulative work experience, as both corporate staff members and as consultants, and shares recommendations for providing highly valuable editorial contributions. The authors also introduce a new concept for innovative editorial methods that meet the technological and productivity challenges facing today’s information design organizations.

Holland, Mary T. and Kristen Sutton. STC Proceedings (2002). Articles>Editing>Collaboration

Learning the Fine Art of Reviewing

If you asked me what the most painful part of being a technical writer is, my answer would be: 'Getting reviews on time. Getting good feedback and inputs on your work.' For me technical writing has been very pleasurable because I hardly got any review comments. My morale has therefore been very high. Project managers, developers and others are so busy trying to come up with good software (read trying to fix all the goof-ups and bugs!) that they usually tend to give documentation lesser importance. User manuals, who reads them anyway? We do not have time for it!

Kamath, Gurudutt R. IT People (2003). Articles>Editing>Collaboration>Technical Writing

The Nature of the Interchange Between Editors and Authors

Editors, if allowed to interact with authors on a level above the comma, could often help authors negotiate new meaning as authors struggle to translate their ideas into writing.

Document Design (2001). Articles>Collaboration>Editing

Now That You've Got a Double Agent, What Do You Do With 'Em?  

Having demonstrated the importance of acquiring a double agent for writing projects, we now want to explain the best ways to successfully indoctrinate a double agent. This paper will help you prepare for, orient, train, and become a mentor for a double agent to help make him or her an effective member of your writing team.

Fisher, Judith R., Karen L. Mobley and Michelle M. Wright. STC Proceedings (1994). Articles>Writing>Technical Editing>Collaboration

The Physics of Reviewers

Subject-matter experts, managers, and other reviewers tenaciously resist our nagging to review documents properly, often delaying reviews until it's too late to do a good job. It's not that they inherently oppose quality control; rather, the problem's in the amount of work required to review something thoroughly, and 'work' is a physics concept. Conveniently, reviewers--like falling objects--follow the same laws of physics as the rest of the universe, and understanding those laws helps you predict reviewer behavior and take appropriate countermeasures.

Hart, Geoffrey J.S. Geoff-Hart.com (2001). Articles>Editing>Collaboration

Planning and Leading a Successful Review Meeting  

Experienced and novice technical communicators can plan and lead successful review meetings by following this 4-step process: l—Plan ahead. 2—Use an agenda as a road map. 3—Wrap up. 4—Follow up. Although a faceto- face meeting is often the easiest way to get formal feedback on an information product, there are situations in which you should not hold a meeting. If a meeting is appropriate, however, there are specific things you can do to prevent or handle typical problems. Leading a successful meeting involves making a series of conscious choices to make better use of everyone’s time.

Hansen, Lauren Y. STC Proceedings (1996). Articles>Editing>Collaboration

Reviewing a Peer's Work  

If we've been asked by a peer to review his or her work before it is sent out to be scrutinized by the world, our job is to neither edit nor rewrite the information. Our job is to give helpful, specific feedback about where the information communicates well and where it needs work. The more we understand about how to review a peer's work effectively, and how doing this is different from editing, the better feedback we can provide.

Gillihan, Dana L. STC Proceedings (1993). Articles>Collaboration>Editing>Writing

The Role of the Editor in the Technical Writing Team

Editing today covers far more than printed materials. In this discussion, I am assuming a technical editor may be required to deal with: printed materials (for example, books, pamphlets, quick reference cards); electronic (for example, online documentation, online help, web pages); video scripts; computer-based training materials. I am also assuming that the audience for the material being edited is not comprised of other technical people; or if it is, the editor is not the person responsible for ensuring the technical accuracy of the material.

Hollis Weber, Jean. Technical Editors Eyrie (2002). Articles>Editing>Collaboration>Technical Writing

Strategies for Peer-Reviewing and Team-Writing

When you peer-review other people's writing, remember above all that you should consider all aspects of that writing, not just--in fact, least of all--the grammar, spelling, and punctuation.

McMurrey, David A. Illuminati Online (2001). Articles>Collaboration>Editing>Writing

Strategies for Working with Authors: How to Foster Productive Author-Editor Relationships  

Learning to be a good editor requires much more than learning the rules of grammar, diction, spelling, and punctuation. Editing requires a complex skill set, including an eye for document design, an awareness of how different document features affect readability, an understanding of how to manage the document development process, including the role of an editor in that process, and the ability to work with a variety of not just documents, but the creators of those documents--the authors. This paper discusses strategies to enable editors to develop productive, collaborative relationships with authors. Within the context of a capstone course in technical editing, students describe various strategies they used to develop editing plans, negotiate levels of edit and conduct editor/author conferences, and how they managed editing projects involving real authors and their documents.

Grady, Helen M., Ericka T. Mayweather, Brian W. Davis and Andrea M. LaPlume. STC Proceedings (2004). Articles>Editing>Collaboration

The Technical Editor as Diplomat: Linguistic Strategies for Balancing Clarity and Politeness     

An essential component of technical editors' work is to convey to writers how their documents would benefit from revision. This task is potentially sensitive, given writers' intellectual and emotional investment in the documents they have created. The sensitive nature of the editing process is clear in Rude's (2001) advice to students of technical editing: '[A]void words that suggest inappropriate editorial intervention, especially change ' (p. 43). Rude's advice suggests an awareness of the difficulty inherent in imposing oneself into the creative process of another person. Because of the defensiveness they might encounter in writers, editors must be cognizant of how they carry out their jobï¿the language they use to convey necessary changes to writers' documents. The language editors use can either facilitate good working relationships with writers or degrade those relationships.

Mackiewicz, Jo M. and Kathryn Riley. Technical Communication Online (2003). Articles>Editing>Collaboration

"Why Do We Need Editors Anyway?" Overcoming the Obstacles Facing a New Editing Group  

In the corporate arena, an editing group (particularly a newly formed one) sometimes finds it difficult to be accepted as part of a communications team and may spend an inordinate amount of its energy seeking to justify its existence. Barriers to acceptance and credibility include lack of trust and misunderstanding about what editors do or what value editing imparts. Editors can overcome these obstacles, however, through a combination of consistent work practices, clear and frequent communication with writers, and an ongoing program aimed at demonstrating the practical value of editing.

Collins, William L. STC Proceedings (1995). Articles>Editing>Collaboration

Writer-Editor Interactions: What Works?  

Successful writer-editor relationships require a commitment from both parties to teamwork, open communications, and shared accountability for the success of each project. The benefits from this ejj?ort include better igformation products for users and a more congenial working environmentfor you. Equally important, your clients will develop cor@ence and trust when they see a project’s writer and editor combining their skills and collaborating on shared project goals.

Collins, William L. and Susan M.J. Lester. STC Proceedings (1997). Articles>Collaboration>Editing>Writing

Writer-Editor Relationships in Revisions

Editors, professional or otherwise, can be annoying individuals. The trick is to focus on the helpful parts of that annoyance and try to ignore the less-helpful parts.

Hart, Geoffrey J.S. Geoff-Hart.com (1995). Articles>Writing>Editing>Collaboration

Writing Across the Curriculum

The phrase 'writing across the curriculum' is relatively new, as far as I am aware. I want to examine its underlying meaning, its various administrative forms, and its implications for the faculties of colleges and of high schools to look at the theory, the practice, and occasionally the history of the notion.

Kinneavy, James L. ADE Bulletin (1983). Articles>Editing>Writing>Collaboration

Writing Programs and the English Department

A couple of years ago John Gerber, in an article in the ADE Bulletin, urged a broadened definition of 'literacy,' one that would encompass all study relating to linguistic artifacts, from the most elementary reading and writing to the most differentiated scholarship and composing. Nearly all college English departments do include much of this broad range, but the inclusion is rarely an integration. Instead, there's the English major and the freshman composition program and the creative-writing courses and, sometimes, the courses for nonmajors: film, popular culture, folklore; business and technical writing; and so forth. In large departments different faculty members may specialize in one or another of these units, and the chairman, who is supposed to be running the whole six-ring circus, can scarcely get the different sorts to talk to one another. What integration occurs begins and ends with the yearly departmental cocktail party.

Johnson, Paula. ADE Bulletin (1979). Articles>Editing>Writing>Collaboration