Developmental Editing

What It Is

As technical writers, we’re often called upon to do a developmental edit on existing documentation. As a web search quickly reveals, “developmental edit” means different things to different people. In fact, it can mean different things to us as well, depending on the client, the material we’re working with, and the resources (such as time) that are available for the work.

The Editing and Writing Continuum

At one end of the editing/writing continuum is the type of edit that most people have heard of: the copy edit. A copy edit is primarily the correction of spelling, punctuation, and grammar. There are different levels of copy editing. For example, if time is tight, a copy edit might include only the checking of spelling and punctuation and the correction of the most egregious syntax and grammar errors, such as plural nouns with singular verbs or missing articles (a, an, the). When sufficient time is available, a heavier copy edit could also include fixing more complex grammatical constructs, ensuring that headings are clear and consistent, identifying vocabulary inconsistencies, and so on.

At the farthest end of the continuum lies document creation, which includes planning, researching, and writing documentation from scratch.

Somewhere in between lies the developmental edit of an existing document, which might include evaluating the overall organization, identifying possible missing material, and identifying ways to improve the general quality of the writing. In some fields, such as mainstream publishing, where an author’s name goes on a book, the developmental editor might simply provide feedback to the author and let the author make the identified improvements. In technical writing, however, most often the original writer turns the material over to a technical writer or technical editor, who makes all further revisions.

It’s often hard to tell where copy editing, developmental editing, and writing begin or end, because creating, updating, or improving a document often requires all levels of work. For our purposes, let’s consider a developmental edit to be a detailed rework of an existing document, which could include activities ranging from heavy copy editing through the planning and writing of considerable new material.

Goal of Developmental Editing

As with any work that a technical writer does, the primary goal is to provide the information that a document’s reader needs, delivered in the most effective manner. The actual work that can be done is often limited by time or money, but within those resource constraints, we always try to give the reader, and therefore the client, the most benefit possible.

This is no different from any technical writing or editing that we do. The ideal process is to identify the document’s likely reader (the audience), the tasks they’ll most likely need to do, and how the product can help them accomplish those tasks. A large part of that is achieved by making sure that the documentation is:

• Clear, so that the reader doesn’t become frustrated or, even more important, doesn’t misunderstand important information
• Well organized, so that the material makes sense as presented and so that the reader can easily find any necessary material
• Concise, because no one wants to spend a lot of time reading extra sentences or even words
• Complete, although not so detailed that the reader is burdened by reading obvious details

From Technical Writing to Developmental Editing

Developmental editors might do some of the same tasks that a technical writer would do when first creating a document. For example, if no documentation plan exists for the document being evaluated, a developmental editor’s first step might be to sketch out such a plan. It’s difficult to ascertain whether a document is fulfilling its requirements if the requirements aren’t clearly specified or agreed upon. A documentation plan identifies, among other things:

• Who the document’s audience is
• What problems or tasks the readers have that this product and documentation is supposed to help them with
• What concepts the readers need to know
• What background and skills the readers need to have
• What parts of a product or concept are most likely to give the readers challenges
• How the documentation will be delivered and how the reader will use it (in what environment)

Using this plan, it’s easier for the developmental editor or technical writer to ensure that the vocabulary, organization, and content are appropriate for the intended audience.

From Copy Editing to Developmental Editing

There is certainly overlap between what a copy editor looks for and what a developmental editor looks for. A developmental edit, however, focuses on broader, more content-oriented issues in a document, such as:

• Overall organization and clarity
• Overall presentation and approach
• Completeness of the information provided

Clarity

Where a copy editor in a heavy copy edit might look for grammatical errors and awkward phrasing, such as the use of passive voice, a developmental editor takes sentence-level and paragraph-level clarity one step further by asking:

• If this passive sentence is changed to active voice, does it reveal that it’s unclear who or what is doing the action? Or does it suggest additional steps that the reader must take or concepts that the writer must explain?
• If this complex sentence rolls on for four or five lines and is hard to read, does breaking it into multiple sentences reveal a concept that wasn’t clear to the original writer? Or does it suggest concepts or vocabulary that are missing?
• Does the flow of ideas in a paragraph progress logically, or does it jump back and forth between ideas or forward and back in sequence?

Organization

Where a copy editor checks the table of contents to make sure, for example, that headings have appropriate subheadings and that the capitalization is consistent, a developmental editor might look at the major headings and the content under the headings, thinking about whether information is introduced in the best possible order, and ask questions such as:

• Is the information that the reader needs for understanding a concept introduced before that concept is discussed?
• Is there enough overview to provide context?
• Does overview material get bogged down in detail that should be handled with a reference to further discussion?
• Does the document provide sufficient ways for readers with different needs to access the information, such as alphabetical organization, conceptual organization, and functional organization?

Consistency

Where a copy editor typically looks for consistency at the level of voice, parallel construction of sentences and paragraphs, and so forth, a developmental editor might look for consistent use of terminology or a parallel approach to different topics, and ask questions such as:

• Are terms adequately defined?
• Are multiple terms used for the same concept?
• Is the same term used for multiple concepts?
• Is the same kind and amount of information given in different areas?
• Are all parts of the document addressed to the same audience?

Completeness

In addition to reviewing what is already there, a developmental editor looks for what isn’t there. The text might suggest questions without providing answers, or the answers might be hard to find. The developmental editor might ask questions such as:

• Is this topic developed in more detail elsewhere? If so, could it be referenced here, or could the topics be rearranged to form a better connection?
• What happens in this or that case?
• How would the reader do this other related thing?
• For each element that’s mentioned, is it clear how and when it’s used, what values it can have, what the values mean, what the results are, and how this element relates to other elements conceptually and sequentially?
• If readers had nothing but this document, can they figure out how to accomplish the tasks that they need to do? (Or at least that have been identified as the tasks that this document should help them with?)

In Conclusion

The skills and tasks of developmental editors and technical writers overlap considerably. Just as one would use a skilled technical writer to create excellent new documentation from scratch (see The Ideal API Reference), one would use a skilled developmental editor or technical writer to ensure that an existing draft document eventually becomes an excellent document as well.