Working with a Technical Editor

Editor’s Note: The following piece by Jean Hollis Weber is part of our collection of “classics”–articles that stand the test of time no matter how many technologies come and go.

Imagine these scenarios:

  • You have started work at a new company or on a new project (as an employee or a contractor), where your work will be reviewed by a technical editor as well as by the Subject Matter Experts (SMEs).
  • You are part of a growing writing team, and your company has just hired an editor to join the team.
  • The material you write will be part of a multi-author project, and the editor will impose a “single voice” on the results.
  • You are writing articles or books to be submitted to a commercial publisher, and one or more in-house editors will be working with you to produce the final product.

If you have never worked with a technical editor before, you may be wondering what to expect, and what the editor will expect from you. If you have worked with an editor before, you probably have some expectations about the relationship. Whether your past experiences were good or bad, you may be quite surprised to discover that the new editor’s expectations are rather different from yours. This article looks at some aspects of the writer-editor relationship and what each of you can do to get the best results out of working together.

 

What are the Editor’s Role and Responsibilities in Your Company?

The roles of the writer and editor may vary considerably depending on the organization and the industry. What’s common in software documentation is often quite different from the usual practice in commercial publishing or engineering.

If the editor or your manager doesn’t tell you what the editor’s role and responsibilities are, ask! Bumbling along with unstated expectations is a sure way to develop misunderstandings on everyone’s part.

Here are some of the things a technical editor does:

  • Get involved in a writing project from the planning stage through to completion
  • Plan (or assist in planning) the documents necessary for a project: Content, cost, timing, and other resource requirements
  • Coordinate the production of several documents on one product (often written by different people)
  • Set and enforce standards for the company’s publications and for a particular project
  • Determine the suitability of material for the target audience
    • Organization
    • Presentation
    • Word use
    • Illustrations
    • Comprehensibility
    • Completeness and correctness
    • Retrievability (index, table of contents)
    • Tone
    • Coherence
    • Gender-neutral style
  • Assist writers in developing material, particularly its logical order and structure
  • Advise writers on the appropriate use of graphics, wording of headings, figure and table captions, page breaks, and index and glossary entries
  • Perform whatever levels of edit are necessary
  • Review, edit, and rewrite all copy as necessary
  • Supervise graphic artists and editorial assistants
  • Fix problems in files, including layout
  • Produce a final camera-ready copy or the electronic equivalent; liaise with printers or Web site developers; examine and approve page proofs or electronic equivalents; resolve associated problems

In addition, editors may be required to

  • Provide additional or missing material
  • Edit copy written by a person unskilled in English
  • Assist with translations, usually in the idiomatic expression in English of technical concepts
  • Edit for technical content
  • Organize reviews of material for technical accuracy
  • Test written procedures against the product (software or hardware)

Reading the list above, you probably said, “But that’s the writer’s job, not the editor’s job!” about several of the items. That reaction is common; it shows the assumptions you are bringing to the relationship, and why it’s so important to explicitly state what the editor’s role is in any particular situation.

In my work as a technical editor, I’ve encountered many different ways that writers and editors work effectively together. Whose job includes which items on the list (as well as other items not on the list) depends on several factors, including personalities, skills, experience, product knowledge, time available, and the overall workflow in a company. I’ve seen the roles and responsibilities change from one project to another within the same company, with the same people involved–with excellent results.

 

What Do You Mean When You Say “Editing”?

Buried in the list of possible roles and responsibilities was the item “Perform whatever levels of edit are necessary.” Many problems arise when people assume that their definitions for the different types and levels of editing are the same as everyone else’s definitions.

The Levels of Edit, an excellent paper by Robert van Buren and Mary Ann Buehler (1980), divides editing into nine types of edit, which are then grouped into five levels of edit. I won’t go into all the details here, but the categories are coordination, policy, integrity, screening, copy clarification, format, mechanical style, language, and substantive editing.

In practice, most organizations tend to divide editing into three types:

  • Substantive editing, which deals with the overall logic, structure, and usability of the publication
  • Copy editing, which typically includes screening, copy clarification, and language edits
  • Production editing (sometimes called a quality edit), which includes policy, integrity, format, and mechanical style edits

I divide editing tasks into “rule-based” and “analysis-based” edits. This classification provides a basis for determining which editorial decisions are negotiable with the writer and which are non-negotiable.

Rule-based editing covers ways to make a document correct, consistent, accurate, and complete, using standards and guidelines. Rule-based editing is usually non-negotiable with the writer: The editor enforces the rules, as specified by the company. Some examples:

  • Spelling, grammar, punctuation, capitalization, hyphenation
  • Adherence to legal requirements (copyright, trademarks, and so on)
  • Internal consistency, typically to do with design: Typography, layout, and illustrations
  • Bibliographic references and citations

But rule-based editing is not enough; the document can still be inappropriate for the intended audience.

Analysis-based editing covers the process of evaluating a document for concept, content, organization, form, and style, to make it more functional and appropriate for its readers–all the items included in substantive editing. Much of this type of editing should be negotiable; the editor should suggest improvements rather than make corrections. Problems arise when the difference between “enforcing the rules” and “making suggestions” is not clear.

 

Who Does What, When, and in Which Order?

What’s the best way to organize the division and flow of writing and editing work? I am familiar with several possibilities, depending on the individuals involved, the project, and the organization.

Some questions to consider:

  • How many people are involved in the project?
  • What are their skill levels?
  • What are the time constraints?
  • How much other work does each person have to do?
  • How well do team members get along with each other? Do they respect and value each other’s work (both methods and results)?

Many scenarios are workable. Some typical scenarios are:

The editor receives the material from the writer, types in changes, and sends the result directly to layout and production. This method is best when the writer is not available (for example, has left the company) or fast turnaround is required (for example, news). It may be used in any situation where the editor has the final say. The writer may proofread a printout of the final layout.

The editor types in questions and changes (without using any revision features), and the amended file (or a printout) is returned to the writer to check and answer questions. This method is best used when the editor has the final say, or when the writer wants to see only the finished material, not all the changes. An example is material submitted for inclusion in a report compiled from many contributors and revised by the editor.

This is also a useful method when the writer and editor are comfortable working as a team. Often the most efficient way to produce top-quality material to a tight deadline is for the writer to do the research, organize the material, and write a draft which the editor will then turn into polished language and formatting, adhering to the style guide. This arrangement frees the writer to concentrate on the meaning of the text, without having to pay attention to details like capitalization, what terms should be in bold type, word usage (press/select/choose/click), and other important but distracting consistency issues.

The editor types in changes and questions (using the revision feature, so changes are marked), or marks up a printed copy of the document, and the file or marked-up copy goes to the writer to accept or reject the changes or to request clarification if required. This method is best when the writers are experienced or will have their names on the resulting document, or when the writers are inexperienced and markup will assist in their education.

The editor marks up or types in changes and questions and discusses the markup with the writer. This method is best when training inexperienced writers (or those new to the company style), or if the editor has many comments or questions that are best resolved through discussion.

The editor provides comments in a separate file and the writer or layout person inserts them into the document. This method is best when the editor doesn’t have the appropriate software to edit the file directly and/or layout is most important (for example, in brochures). The writer usually proofreads a printout of the final layout.

 

At What Stage Should a Document Be Sent to the Editor?

All together now: “It depends!”

As you have seen, editing is not just checking a document for errors after the writing has been completed. That is one type of editing: The final production or quality edit. For a final edit, the document should be finished; no material is missing, all previously-identified changes have been made, the final illustrations are in place, and so on.

Much editing is (or should be) done at various stages in a document’s development. For example, substantive editing should be done early, perhaps on a sample of the material, at a stage when making major changes (structural or stylistic) will not require major rewriting. Editing sample sections can save time and effort by alerting writers to possible problems. At that stage, much material may be missing (though placeholders or topic headings should indicate where the missing material will go), illustrations may be in draft form, page layout may not even be started, and rigorous application of the company style guide has not been done.

Copyediting might be done several times and in different levels of detail. Before a document is sent for copyediting, the writer should at least run it through the spelling checker, but how much other detail work should be done depends on the agreement between the writer and editor. Depending on the draft, here are some things the editor might expect the writer to have verified:

  • Text meets all the requirements of the style guide regarding capitalization, punctuation, word usage, highlighting (bold, italics) and font usage, spelling out of numbers, parallelism, and so on.
  • All numbered lists are numbered correctly.
  • Figure captions are consistent with the text and the illustration in the figures (for example, references to the names of dialog boxes and fields are correct).
  • Page breaks are as they should be (if page layout has been done).
  • Clickable links work.
  • Required front and back matter (preface, trademarks notice, index, glossary) are included.

Should Edits Be Done Before, After, or During Technical Reviews?

In circumstances where technical reviews are conducted, three scenarios are common. Which one is best depends on the situation.

Technical reviews are conducted before editing. This method is best when a complex document is likely to be changed substantially by SMEs during their review, so that the copy is reasonably stable and accurate before it reaches the editor.

First-pass editing is done before technical reviews. This method is best when dealing with inexperienced writers or those unfamiliar with the company style, so that the review copy is free of grammatical, spelling, word use, and other errors that might distract the SMEs from focusing on the accuracy of the information.

Technical editing is done as part of the technical reviews. This method is best when time is very limited, or when there is no advantage to editing before or after the technical review.

 

What About Personality Issues?

The writer and editor should work together to achieve a goal of producing the best possible document from the readers’ point of view, within time and other constraints. This often means compromise on both sides; no document is ever perfect, much as one or both people may want it to be.

The editor should be considerate, polite, and tactful when dealing with writers, while still offering ruthless commentary. In return, writers should be tactful when responding to editors’ comments, while not meekly accepting every suggestion; editors do make mistakes, too.

Some things that writers appreciate from an editor are:

  • An editing schedule
  • Timely edits
  • Private, constructive editorial conferences when appropriate
  • Assistance, when requested, with indexing, figures, tables, examples, and any other questions
  • Training to overcome weaknesses
  • A different perspective on the content and organization of the document
  • Collaboration rather than confrontation:
    • An emphasis on improvements, not corrections
    • An emphasis on the readers’ needs, not the editor’s personal preferences
    • Negotiation, not dictatorship, with previous definition of what’s negotiable and what isn’t
    • Explanation, if needed, about why the editor has made specific suggestions

Sometimes, of course, agreement cannot be reached. At that point, whoever has the authority to make the final decision must simply make that decision. If management has failed to establish in advance who has authority, serious conflicts can result.

 

Conclusion

This article has examined some of the issues and possible scenarios for writers and editors in working together. Editing includes a wide range of activities performed at different stages of a document’s development. A publishing team needs to understand those activities and agree on a schedule that contributes to efficiently producing quality material, preferably in a cooperative and supportive atmosphere.

Writers, editors, and managers need to ensure that everyone understands the editor’s role and responsibilities in the publishing team. An editor’s status and authority may vary greatly, depending on the culture of the organization and the needs of a particular project, as well as on the editor’s knowledge, skills, and experience. The information in this article provides a good start toward developing common goals and a mutually beneficial working relationship.

 

Reference

van Buren, Robert and Buehler, Mary Ann, The Levels of Edit, 2nd edition, Jet Propulsion Laboratory, Pasedena, CA, January 1980, JPL Publication 80-1, 26 pp.

Jean Hollis Weber is a technical editing consultant based in Australia. She has over 25 years of editing experience in scientific, engineering, computing, and other high-tech fields. Jean maintains the Technical Editors' Eyrie Web site, at http://www.jeanweber.com

Read more articles from Jean Hollis Weber