2. Working With an Editor

Writing computer documentation involves converting a hodgepodge of information supplied by engineers and marketing professionals into a useful, well-written document. The final document often is a result of efforts from the entire publications team, including writer, editor, designer, illustrator, and production coordinator. However, the content of the document is most closely developed through the work of writer and editor.


Role of an Editor

An editor helps a writer to focus on content and effective presentation and provides another set of eyes to check all details. An editor's primary goal, as stated by Robert Bly and Gary Blake in Technical Writing Structure, Standards and Style (McGraw-Hill, 1982), is "to help the reader by making publications easier, less time-consuming, and more enjoyable to read."

The partnership of writer and editor produces easy-to-use, high-quality, effective documents. One writer explains:

    A savvy writer knows that a good editor is an indispensable ally. By approaching your work as a customer would, the editor is able to provide you with insight on how your work is likely to be received and interpreted. At the same time, the editor is able to restore the freshness of perspective that the writer necessarily loses while working on the same manual day in and day out.

Any editor is concerned with use of language, flow, tone, grammar, punctuation, capitalization, spelling, sentence structure, consistency, and so forth. However, a technical editor also is concerned with technical content, compatibility of the technical depth with the reader's background, effective communication of technical information, consistent use of technical terms and symbols, and competent coordination of text and artwork.

By marking something and suggesting an alternative, an editor indicates to a writer that the original may be, for example, misleading, awkward, imprecise, confusing, or incomplete.

One staff technical writer, who also writes books for trade publishers, described an editing experience:

    My most recent "noncompany" editor edited a book I wrote. He didn't cross out one word. He didn't change anything stylistically. Instead, he made suggestions about what should be added, what could be made more clear, what the reader would want to know - hundreds of suggestions that greatly improved the quality of the book.

    The editor and I were both professionals, each with our own set of skills. We worked together to create a product that received extremely favorable reviews in the popular press.

    Too often it is impossible for writers to be objective about their own writing. As the first reader of a writer's work, the editor is in an important position to elevate the quality of that work. Writer and editor, together, should come to an understanding of what relationship will produce the best possible quality of writing.