Alternatives to the Paragraph

'It's all in the manual.' How many times have you heard that - or said it in frustration? After all, when you are the person who wrote the manual, you know that all the answers are there. But time and again readers can't find what they need to know, or don't understand the material. Before you blame the reader, look again at how you've presented the material.

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

Angels and Copy Editors Defend Us!

Tinkering with the author's words simply because 'I would not write them that way' is not discretion, but interference. Preserving the author's authentic voice is as important as enhancing its presentation so as to maintain the authority of the words. Of what, then, does the enhancing consist? And how does editorial discretion fit in?

Fothergill-Brown, Ann. Writer's Block (1999). Articles>Writing>Editing

Beyond Gutenberg

Editing must change for the Web, but perhaps not so much as you think. In paper publishing, different documents require different rules and procedures: An annual report requires more editing and more attention to detail than an office memo. Similarly, not all Web documents are equal.

Ivey, Keith C. Editorial Eye, The (1996). Articles>Web Design>Editing>Writing

Bug Reports: Your Road to Visibility  

Argues that technical writers have a professional duty to report defects in software and presents examples of software problems that require bug reports.

Leritz-Higgins, Sarah E. Intercom (2002). Articles>Writing>Editing

Can the Computer Improve your Writing Style?  

We have spell checkers. We have grammar checkers. What we really need is a style checker.

Cohen, Gerald. STC Proceedings (2000). Articles>Writing>Editing>Word Processing

Combine Writing, Editing and Design in Your Employee Publication

After more than a decade of working in the corporate environment, I have finally accepted that readers need to be enticed by more than the promise of a good read: They need proof. They want a visual two-second test-drive before they decide whether or not to spend precious minutes on a particular page. This is not to say that corporate readers are not discerning or that sloppy copy reads any better when dressed up with elaborate design. The truth is that in any corporate publication, a great article won't be read if the layout is poor. Similarly, a stunning design falls flat if the content doesn't live up to it.

Dower, Sophia. Communication World Bulletin (2007). Articles>Writing>Editing>Newsletters

Developing Evaluation Criteria

We encourage you to adapt criteria to your specific communication assignments. You might specify, for example, the technical or scientific content for which your students are responsible. You might also specify how students will address communication concerns such as audience, purpose, context, organization, support, design, and expression.

University of Minnesota. Articles>Editing>Writing

Developing Indexes

As a technical writer, you'll typically have to create indexes for the print books and for online helps you develop. The type of index we mean here is the classic back-of-book index that shows page numbers on which topics and subtopics occur within the book. An online index is much the same except that you supply hypertext links rather than page numbers.

McMurrey, David A. Illuminati Online (2004). Articles>Editing>Indexing>Technical Writing

Editing All the Legalese the Law Allows

Strictly speaking, legalese isn't intended for use outside a judicial context, but quasi-legalistic writing, with its officious tone, wordiness, and complex terms, percolates into business, government, and public interest documents. It's a parroting of the real thing -- which is already hard to swallow -- and there's a lot of it around. That kind of legalese demands to be edited, because people will do almost anything to avoid reading it.

Mayhew, Paul and Elizabeth McBurney. Editorial Eye, The (1997). Articles>Editing>Legal>Writing

Editing and Revising With Flair  

Samuel Johnson wrote 'What is written without effort is in general read without pleasure.' The wisdom contained in this pithy directive should serve as an excellent guide for writers who edit and revise documents to imbue them with a sense ofpanache. While proper syntax, diction, and usage are three primary elements in the editing and revising process, other important considerations include: (a) eliminating redundancies; (b) avoiding jargon; (c) cleaning bureaucratic expressions; (d) using active andpassive voice appropriately; (e) avoiding wordiness; and Gf) editing for slips in grammar, punctuation and mechanics.

Wadia, Mickey. STC Proceedings (1997). Articles>Editing>Writing

Editing Tests for Writers  

Times are hard, and many former writers are pounding the dirt looking for work. Some who have extensive experience with peer review or revising documents are expanding their job searches to include careers as editors. However, new editors often face a barrier to entering the profession: the editing test. Rather than taking a chance on unproven candidates, publishers and other clients typically ask would-be editors to review short documents that test three main aspects of an editor’s skills.

Hart, Geoffrey J.S. Intercom (2003). Articles>Editing>Writing

Editing Web Pages: A Second Look  

How to edit Web pages--with revision tracking--using Microsoft Word.

Hart, Geoffrey J.S. Intercom (2004). Articles>Editing>Web Design>Writing

Editing Your Own Documentation  

Technical writers sometimes fall into the trap of thinking that the user is stupid. I have often heard technical writers say things like 'well, if the user can't figure that out, maybe he’s in the wrong job!'

Docsymmetry (2003). Articles>Documentation>Editing>Technical Writing

Editing Yourself

Here are some tips that helped me edit my own writing.

Leigh, Heather. Crazy for Words (2007). Articles>Editing>Writing>Technical Writing

Editors: Who Needs Them?  

Editors can play many roles, which, as the need arises, might overlap with those of the production editor, the writer, and even the writing manager. Within the category of editing itself, the editor can perform different levels of edit: formatting, language, substantive. Every pubs group needs an editor, even if only on a parttime basis. The qualities a manager should look for in an editor are somewhat different from those required in a writer. Editors are less likely to have a technical background. They must not shrink from the possibility of confrontation, and yet must be able to give constructive criticism in a manner that the writer will accept and welcome.

Arakelian, Caroline, Lisa Braz, Diane Kirsten-Martin, Bob Nowacki and Carol A. Ranalli. STC Proceedings (1998). Articles>Editing>Writing

Electronic Outlining as a Tool for Making Writing Visible

The electronic outlining software found in many commercial programs, when projected on the classroom wall, helps us train students in the main activities involved in creating an outline. Freed from paper, the electronic outline allows continuous revision, encourages multiple iterations of the many interdependent activities involved in research, planning, writing, and revision, and serves as a focal point for discussion of the ways in which the group is developing an ongoing consensus, as part of a larger conversation.

Price, Jonathan R. Communication Circle, The (1997). Articles>Education>Editing>Writing

Experiencing Technical Writing as Textual Coordination  

This paper describes a recent study of how of four technical writers managed the many artifacts (existing texts and information technologies for producing and manipulating text) that mediated their writing process. The author describes the study and characterizes several recurrent patterns of mediation, including textual reuse, remediation of information, and the staging of texts and software programs. The author describes the value of a repertoire of information technologies to technical writing and argues that technological skill should be considered a core competency of the field.

Slattery, Shaun. STC Proceedings (2005). Articles>Writing>Technical Editing>Technical Writing

Final Check: Dotting Those i’s and Crossing Those t’s

You’ve worked long and hard on your article, newsletter, press release, promo brochure or report. Now it’s time to move your baby off your screen and into the world. Not so long ago your baby would have gone either onto a printed page or onto the Web. These days, your words will probably head for both. Even materials such as newsletters, white papers, reports and advertorials that are first published on paper are quite likely to be reprinted, archived or otherwise reused on the Web, perhaps even as an audio file or podcast. People may even blog about your content. What does this mean for you as a business communicator?

Canavor, Natalie and Claire Meirowitz. Communication World Bulletin (2008). Articles>Business Communication>Editing>Writing

Good Writing and Editing: Are They Dying Arts? And, Should We Care?

The answer to both questions: "YES!" Like us, you may be dismayed by the growing quantity of poor writing that bombards us. We see it everywhere, in publications, web sites, newspapers and corporate materials—writing that is not just full of grammatical mistakes and misused words, but is also poorly thought-out, unclear and contains downright confusing language.

Canavor, Natalie and Claire Meirowitz. Communication World Bulletin (2004). Articles>Writing>Editing

Grammar Stammer

Don't you think that it is a tragedy that 95 percent of the people who desire to be technical writers have a poor command over the language? I am sure all of us make a mistake or two, once in a while. But to make it in every sentence and paragraph shows utter disrespect for readers.

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

Hockey Sticks and User Assistance: Writing in Times of Resource Constraints

If you have all the resources you need, do the very best job you can in all respects. But if your resources are tight, ask yourself whether you are writing the essential stuff at a level of quality users will notice. Also, ask whether the value of the documentation you are producing aligns with the economic pressures on your company.

Hughes, Michael A. UXmatters (2008). Articles>Writing>Technical Editing

How to Edit for Content  

Editing involves more than just formatting and inserting page numbers. You need to ask, 'How can I improve the communication?'

Bush, Donald W. Intercom (2003). Articles>Editing>Writing>Technical Writing

Incorporating Peer Review

Peer review is an exercise in which students review each other's written work. Peer review is often connected to revision, a part of the writing process in which writers refine and make substantive changes to their written work.

University of Minnesota (2004). Articles>Education>Editing>Writing

Incorporating Revision

Revision refers to the process of reviewing one's work and making changes (either local or global) to improve the writing.  Most teachers of writing encourage students to revise their work by creating drafts and going through a process of review -- either by having teacher review drafts or having other students review drafts.

University of Minnesota (2004). Articles>Education>Editing>Writing

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