I manage a group of editors at a software company. This topic describes how we strive to achieve consistency in editing software documentation among a group of editors both within a department and across divisions in a large company. We have a staff of 14 editors that serve five large writing departments. Our editors are excellent grammarians before they come to SAS, but they also get considerable training and mentoring in SAS specific guidelines when they join our staff. I acknowledge that it’s impossible to achieve 100% consistency across all editors, but consistency is worth striving for for several reasons.
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.
Marking up paper is still the most common way to review documents, but online review is critical if you work as part of a distributed team. There are advantages to online review even if you sit only a cubicle away from your reviewer. Here are few tips for making your online reviews go smoothly.
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.
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.
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.
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.
Discusses the use of computer-generated information about what has been revised in the display of editing in word processors.
Even a newspaper like The Times, with layers of editing to ensure accuracy, can go off the rails when communication is poor, individuals do not bear down hard enough, and they make assumptions about what others have done.
Even if an editor loves, loves, loves your work, she is still likely to have to shepherd it through some kind of review process — either internally, in the case of a trade house, or to external academic readers. Many manuscripts die that way, despite the "interest" of the press. Those that are not outright killed can be wounded and sent back to you for some critical care.
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.
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!
Editors are craftsmen, ghosts, psychiatrists, bullies, sparring partners, experts, enablers, ignoramuses, translators, writers, goalies, friends, foremen, wimps, ditch diggers, mind readers, coaches, bomb throwers, muses and spittoons -- sometimes all while working on the same piece.
Track Changes in Microsoft Word is an indispensible tool for editing, but it is not the best tool for the job in every editorial situation. You may find that both tiny details and big-picture edits cause you-and your reviewers-to want less tracking, not more.
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.
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.
Coordinating a document review can be a tedious process. However, the task is even more difficult when reviewers work in another location and can't quickly exchange comments via paper. Fortunately, technology is presenting writers with new options for handling off-site reviews.
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.
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.
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.
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.
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.