Articles>Writing>Editing

What’s More Important, Content or Process?

While style guidelines can be useful for maintaining consistency across a set (or several sets) of documentation, the editors that I worked with viewed the style guidelines as sacrosanct. Any deviation, no matter how small, was punishable by a nasty email and a sharply worded note to the offending writer’s manager.

Unlocking the Special Powers of the English Language

Editing really is a wonder– it’s like a multiplication of the writer’s brain, a dialogue among various copies of the author. First-draft author is an admirable workman but a bit of a hack; he writes down whatever pops into his head. Second-draft author is slower-paced but has a clearer eye for how the larger story structure fits together, or at least how it should fit once he’s done with it. Third-draft author has a remarkable knack for turning familiar and overused phrases into fresh, surprising stuff, by masticating each line. And so on. All these guys team up to make something great, and none of them could have done it alone.

Writing Great Documentation: You Need an Editor

All good writers have a dirty little secret: they’re not really that good at writing. Their editors just make it seem that way. It doesn’t matter how well you’ve mastered the language; nobody, even grammar geeks, gets this stuff right on the first pass. If you really want to produce great documentation, it needs to be edited.

Do I Really Need a Style Guide?

Style guides recommend certain styles. In the domain of technical communication, we refer to guides for writing style, presentation of content in user documentation and technical documents, and graphical user interface of software and web sites.

More Tips for Writing Well

Be vicious when you edit. Vicious. Follow these recommendations with zealous fervor. They help your writing say what it should in a way we’ll understand.

Misplaced Modifier – Even WSJ Falls For It

“Misplaced modifier” is a frequently committed logical error that even the most prominent publications fall for occasionally. Solution? Move the modifier clause right next to the subject of the sentence.

The Construction of Author Voice by Editorial Board Members

Studies of blind manuscript review have illustrated that readers often form impressions of or speculate about unknown authors' identities in the manuscript review task. In this article, the authors extend that work by examining the discursive and nondiscursive features that play a role in readers' active construction of author voice. Through a survey completed by 70 editorial board members of six journals in applied linguistics and rhetoric and composition, the authors identify quantitative and qualitative trends in reviewers' practices regarding voice construction. Findings indicate that many readers do build impressions of an author's identity when reviewing anonymous manuscripts and that the rhetorical nature of the review task may lead readers to attend more to some discursive features than to others.

Copywriting Tip: Have the Computer Read Your Writing Back To You

You don’t have an office mate willing to read your work aloud? Don’t want to bug someone to read your two paragraph blog post? Have your computer read it to you!

Do I Really Need a Style Guide?

So, after all, I must follow those infernal style guides. I am straight-jacketed. Am I not?

Editing and Publishing

Once the main text has been written, you edit it. Editing means breaking text into sub-documents; pointing out connections to other texts; making sure the document as a whole is in good shape; adding indices and outlines. Editing doesn't necessarily happen after the first text has been written - I mix those stages all the time - but it deserves to be thought of as an independent discipline, because the problems it deals with are different. Most of what people do on the World Wide Web is really editing, not writing.

Editing Modular Documentation: Some Best Practices

Much has been said about the creation of modular documentation - from content management systems, to information architecture, to delivery forms, to the usability of modular content (content being easier to use, easier to understand, and easier to find), and so on. However, not much has been said about the editing of that content, and what the editor's role is in such an environment.

Tech Writers, Grammar, and the Prescriptive Attitude

Prescriptive grammar is useful for teaching English as a second language, but it has little value for the practicing writer. Clinging to it may provide emotional security, but only at the expense of making writing harder than it needs to be. The culture-wide devotion to it will not be changed in a moment. But conscientious writers can at least change their own habits, and make life easier for themselves.

Technical Writing's Big Secret

The big secret in technical writing is that most of the harder documents aren't written by the technical writers at all. In fact, many "technical writers" never do any writing at all. Instead, the drafts are written by engineers or marketers. The technical writers perform editorial functions and provide publications services -- copy-editing, layout, review management, and so on.

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.

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.

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?

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.

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.

Substantive Editing: Building the Logical Inner Sanctum

The inner sanctum of any good piece of writing is a solid, logical core. To produce the logical core, a writer frequently has to synthesize complex information, which means understanding it well enough to transform often muddled and random detail to clear and easy to apprehend expression. Synthesis of new information, being one of the most difficult thinking skills, can require more of a writer than the writer has time for. An editor's job, from the first draft to the last, is to help build the writing around an appropriate logical core. In this workshop, participants will practice techniques that editors can use to make sure that they find, or help the writer find, the core - what users need to know, and the order in which they need to know it. Participants will form groups to scan a document, using a checklist of tips to spot problems in the document's structure. Each group will report its findings to the larger group.

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.

Editing Yourself

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

Nancy's Wordsmithy: Rules You Don't Have to Obey, Part III

The funny thing is, this rule should be running out of steam, because certain standards of written English have changed in ways that make the rule at least partly obsolete. Learning it is kind of like learning to change a cloth ribbon on an old manual typewriter.

More Than Just Error Correction: Students' Perspectives on Their Revision Processes During Writing

Drawing on the second phase of a 2-year study of students' linguistic and compositional processes, this article describes students' reflections on their online revision processes, those revisions made during the process of translating thoughts into written text. The data collected were from classroom observation and post hoc interviews with 34 students, who were observed during a writing task in the English classrooms and interviewed subsequently to elicit their reflections and understandings of their own revising processes. The analysis indicates that students tend to conceptualize revision as a macro-strategy and as a task that is predominantly undertaken as a posttextual production reviewing activity. It also indicates that students engage in multiple revising activities during writing, including many revisions that are not concerned with simple matters of surface accuracy, and many students are able to talk about these perceptively and with insight.

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.

Writing And Editing Stem Overview

As part of the process of developing this overview I went back to some of the Proceedings for STC conferences that were held 10 years ago. I also reviewed issues of Technical Communication that were published at the same time.

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.

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.

Technischer Redakteur

Der Technische Redakteur erstellt und aktualisiert aussagefähige, umsetzbare, verständliche technische Dokumentationen aller Art.

Why I Hate The Body of Your Article

I really don't care what you write about. I am more interested in the format of the article, not your view or take on the subject matter.

Why I Hate Your Article Headlines

Iâ€™m a publisher for numerous sites. Hereâ€™s why I hate your headline and what you can do about it.

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.

Editing Web Pages: A Second Look

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

The Fault of Vacuity

I labeled wordiness the most obvious fault in technical writing. In retrospect, I think I was wrong. I believe the greatest fault our writing can have is vacuity, or lack of substance. We too often write words that say nothing.

Trust Your Instincts As You Write

As I write, and even after I have finished and am proofing my work, I have to be sure to be tuned in to a diminutive little editor who sits to one side of my mind.

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.

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.

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.

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.

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.

Technical Translation: Craft, Not Commodity

Describes the work of translators and suggests strategies buyers can use to find the best translator for their needs.

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.

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.

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.

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.

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!

One Hundred Simple Tech Writing Errors

Here are the 100 writing errors that the author has encountered in his experience. (Followed by the subsequent article 'Ten More Errors in Technical Writing.')

Ten More Errors in Technical Writing

So, well, here are 10 more errors. This time we will focus on grammar and punctuation. Most of these are simplistic and obvious. But then they are too common. As usual, I have slipped in some content for the advanced writers too. (This article is a follow-up to 'One Hundred Simple Tech Writing Errors .)

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.

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.

Writing Drafts

One of the keys to effective technical writing is to write, edit and re-write. Once you have completed the first draft, you will need to review it several times to identify errors and inconsistencies in the text.

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!'

Writing, Editing and Designing: a Unified Process

What's in it for me? That's what magazine readers must see at first glance, or they will flip on by. Winning their attention requires thoughtful blending of words and design from the beginning of the publication process.

"Prescriptive" Audience Analysis: Moving Beyond the Purely Descriptive

Editing and writing both require an understanding of our audience, because without that knowledge, we can't shape our words to help them easily grasp difficult concepts. To understand our audience, we do what all writers and editors do, whether consciously or unconsciously: We create an image of our audience that guides our choice of words, images, and metaphors. This image is variously known as a 'stereotype' or a 'persona'. Keeping that image in mind as we work helps us satisfy the reader's needs, but if we're not careful, it can also cause us to waste valuable time collecting information that doesn't really help us communicate.

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.

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.

Writing Shorter Manuals

Large manuals are expensive to write, produce, and ship, and may make a product seem mare diflcult or complex than it really is. Shorter manuals can decrease telephone support calls, provide a challenge to the writer, and save time and money. With careful planning and preparation, diJjCerent writing and design techniques, and participation in product design, writers can shorten manuals and make users more willing to read them.

Writing and Editing Stem Overview

What could embody this year’s theme of Evolution/Revolution more than the Writing and Editing Stem? On the one hand, we must continue to evolve as professionals by building our writing and editing skills, the cornerstones of our trade. On the other, we must stay on top of the information revolution our industry is experiencing. This stem will help you to do both: build upon the basics and also stay abreast of the new technology and tools that are constantly revolutionizing the ways we do our work.

Writing and Editing Stem Overview

The Writing and Editing Stem of the 42nd Annual STC Conference is designed to provide sessions that speak to the questions of technical communicators today and that also remind us to 'stick to the basics' of our craft(s). In a world of to 're-imagine' the audience and gain new ever-changing technologies, we must perspectives. Find out how to motivate your accommodate both a diverse audience and a audience to learn and then keep ‘em coming back! diverse media. Our goal is to explore (proven and new) methodologies and ideas that can enhance our writing and editing skills and philosophies as we enter the 21st century.

Can the Computer Improve your Writing Style?

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

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.

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?'

Technology: A Blessing for Writers and Editors?

Computers have changed the way writers and editors work. But are we getting the most from the new tools?

Writing Consistently Across Media: Ten Proofreading Tips

Last time I wrote about consistency in online writing. Soon after, I received an email from Leslie Drechsler, a reader in Tustin, CA: 'As a Marketing Communications Specialist, I'd love to hear your ideas on how to successfully implement consistency in an established business,' she wrote. 'I thought developing a company style guide would solve the problem. But perhaps there are other ways to approach it. 'Perhaps this could be the subject of another article.' Here's that article, Leslie.

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.

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.

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?