The importance of technical editing in documentation - By Surya Panneer

“Technical editing involves reviewing text written on a technical topic, and identifying errors related to the use of language in general or adherence to a specific style guide. ...This activity ensures that documentation is of good quality.”- Wiki

“I tell writers when they didn’t say what they meant to say and didn’t tell me what I needed to know” -Judith A. Tarutz

Let us look at a brief perspective on technical editing and the role of a technical editor in the technical communication world. Also, let us see the list of points a technical editor can check while editing any piece of information.

This article is intended for you if you are:

• An editor who edits any type of content authored by technical writers, developers, product managers, or other stakeholders

• A technical writer who occasionally edits the work authored by peers, developers, or other stakeholders

• Someone who is an aspiring technical communicator and would like to learn about editing

• Someone who likes a good read😊

Technical editing

If your project is a forest, ” …technical editing looks at the trees, branches, leaves, and even the veins on the leaves.”

Technical editing is a much broader task than just fixing up “grammar”, removing redundancy, adding commas, or correcting spelling errors. During the technical editing process, the editor evaluates the quality, objectivity, and relevance of technical information. The editor ensures that the content is technically accurate, consistent, clear, comprehensive, and succinct, in all aspects including language and formatting.

The editing activity may vary across industries, but the activity ensures that the content is of good quality and is accessible to your audience. The quality of effort–the depth to which technical editing is performed– is contingent on factors, such as time and cost.

Courtesy: www.cartoonstock.com

Role of a technical editor

A technical editor possesses the knowledge of good writing and makes informed recommendations. Many times, they see what authors do not see. With their editorial acumen, objectivity, thoroughness, and persistence, technical editors enhance the content to the benefit of both the author and the reader. They help authors bring the content several steps closer to the needs of the audience.

Because the editors are not very closely associated with the content, they can represent typical users and simulate the users’ experience effectively. While meticulously examining the smaller details in a piece of writing, as a technical editor, you achieve the following:

• Enhance the work while preserving the originality of the author’s style

• Identify the subtle changes in the mood

• Supply a fresh perspective and help the author take the content to the next level

• Zoom in to the most minor detail without losing the bigger picture.

• Find the balance between the right amount of editorial involvement vs. overstepping the author's role

What you may be editing

In addition to traditional product guides, administrator/user/developer guides, proposals, reports, or reference guides, you may be editing any type of content, such as the following:

• Microcopy

• UI content strings

• Bubble help

• Navigational aids

• In-app guidance

• White papers

• Knowledge base articles

• Infographics

• Videos

• Data sheets

• Sitemaps

• Personas

• Technical descriptions

The technical edit checklist pertains to technical documentation in general and is not applicable only to specific content types.

Before we get to our editing checklist, let us see the underlying concepts.

Levels of edit

The concept of “levels of edit” was introduced by the Jet Propulsion Laboratory in March 1976. This concept helped improve the communication among the writers, editors, and publication managers at the Jet Propulsion Laboratory.

The editorial functions performed at the laboratory were grouped into the following nine categories:

• Coordination

• Policy

• Integrity

• Screening

• Copy Clarification

• Format

• Mechanical Style

• Language

• Substantive

Each edit type consists of a number of editorial functions.

Levels vs. types of edit

The combinations of the types of edit have been identified as levels of edit.

Figure 1 Levels vs. types of edit

Courtesy: https://ntrs.nasa.gov/citations/19760015018

We can summarize that, Level 1 is the most thorough edit and Level 5 is the least thorough one:

Depending on your edit requirements, you can choose the level of edit for your content. For example, if you are required to check only the legal part of the content, you could use the
Level 1 edit that includes the policy edit.

Technical edit checklist

Based on the editorial categories, the technical edit checklist has been defined and covers the related problem areas as follows.

Figure 2 Editorial categories and problem areas

In addition to the following technical edit checklist, you can always fall back on your invaluable “writing instincts”.

In the checklist, the description of the problem area, such as Spelling or Spacing, includes only some of the possible scenarios, and note that the problem areas are not limited to these scenarios. The term “document” in the following descriptions could refer to a page, article, or any type of content.

Language Edit

You can check for details, such as spelling, punctuation, capitalization, and usage of grammar and language.

✔ Spelling

The spelling of a word is incorrect. The American spelling or British spelling norms are not followed according to your content requirement.

✔ Word choice

The usage of the word is incorrect or inappropriate, or can be improved.

For example, recommend using “Run the command” instead of “Execute the command”.

✔ Punctuation

The punctuation mark is not required or missing.

✔ Article

The article is not required or missing.

✔ Subject vs. verb agreement

The text contains a subject-verb disagreement.

More info: Subject-Verb Agreement: Rules and Examples

✔ Capitalization

The text contains a missing or an incorrect capitalization.

✔ Passive voice

The usage of the passive voice affects the clarity and concision of information.

For example, recommend using “ensure that you back up xxxx.xml before updating the password” instead of “ensure that a backup of xxxx.xml is taken before updating the password”.

✔ Dangling/Misplaced modifier

The text contains a dangling modifier.

More info: Dangling Modifiers and How To Correct Them

✔ Antecedent vs. Pronoun Agreement

The text contains a missing, an ambiguous, or an incorrect antecedent for a pronoun.

More info: Using Pronouns Clearly

✔ Ordered/unordered list

The page contains an ordered list in which an unordered list is appropriate or vice versa.

✔ Noun string

The sentence contains a noun string or noun stack.

For example, use “You can find the error details in the error log of the Security Gateway.” in place of . “You can find the error details in the Security Gateway error log.”

✔ Nominalization

More info: Sentence Clarity: Nominalizations and Subject Position

✔ Technical jargons

The text contains a technical jargon that can be replaced with a simpler terminology. The technical terminology has been used without a definition.

✔ Objectivity

The explanation of a concept is influenced by emotions or personal prejudice.

✔ Advertising/marketing language

Boastful or an exaggerated language is used.

If you are working on marketing content, this problem area may not be applicable.

Format Edit

You can check the textual and visual elements for their conformity with the appropriate formats.

✔ Template style

The template style, if available, is customized or incorrectly applied.

✔ Infographic

The image is not legible; the usage of colors can be enhanced. The labelling, ordering, or comparison of the infographic is missing or incorrect.

✔ Page element

 The page element, such as topic header or footer, is missing or incorrect.

 ✔ Spacing

The text contains incorrect spacing between words or paragraphs. The text consists of widow or orphan instances.

Functional edit

Ensure that the content does not lack any of the following against the functionality of the product.

✔ Clarity

The explanation is unclear, though correct, does not suit the audience. Data visualization lacks clarity.

✔ Correctness

Conceptual, procedural, process-related, or factual information is incorrect or missing. The infographic or microcopy contains incorrect or missing data.

✔ Comprehensiveness

Explanation of a concept is too abstract. Relevant information is missing or inadequate.

✔ Anthropomorphism

Words or phrases that convey intention or desire (such as, refuses or wants or is interested in), intellect (thinks, knows, realizes), or emotion (likes) are used. 

For example, recommend using “In this course, we assume that...” in place of “This course assumes that...”

Substantive edit

You can check the intended use, organization, flow, and strength of the content. You can also check if too much or too less information is present and if similar information is presented consistently across documentation.

✔ Consistency

The information provided in different parts of the document contradicts with each other. The document uses different terminologies to refer to the same subject. For example, you see instances of “supplier” and “vendor” in the same document. 

✔ Cohesiveness

The information does not flow logically. The order of points that indicate the relationships is incorrect.

✔ Conciseness

The text contains expletive constructions or overlapping sentences.

Integrity edit

Ensure that each reference identifies an existing element, such as web page, table, figure, or appendix, in the content.

✔ Cross-reference/Hyperlink

The cross-referenced page is not working any longer. A hyperlink or an email address is incorrect, not functioning, misplaced, or missing.

✔ Sequence

The text contains a missing or an incorrect lettered/numbered sequence. More than one table/image use the same number.

✔ Page element

The ToC does not agree with the headings, figure captions, or table titles. 

Mechanical edit

You can check the style and usage of the content for its conformity with your style guide.

✔ Copyright/IP

The document contains an incorrect legal, copyright, or third-party copyright information. Trademark symbols are missing or incorrectly used. The legal names of the products are incorrectly referenced.

✔ Style guide

The content does not adhere to your organization’s style guide or the principles of good writing.

✔ Abbreviation/Acronym/Initialism

The definition of abbreviation/acronym/initialism is missing.

✔ Document properties

The document properties, such as title, author, subject, and keywords, are not set or incorrect in the document.

Conclusion

“Technical editors provide an essential role in ultimately synthesizing information by adding clarity, value, and usability to present a united voice.” Nowadays, technical editors are often involved early on in the product design/development stage to actively influence decisions that impact the product usability. They do not let something go because the content reflects their work as well as the author’s.

“Good editing is unnoticed by the reader!”

Well, let us conclude the “substantial” topic on a “lighter” note! 😊

Courtesy: www.cartoonstock.com

References

• The levels of edit - https://ntrs.nasa.gov/citations/19760015018 

• Technical Editing - The Practical Guide for Editors and Writers by Judith A. Tarutz 

• Anne Enquist, Substantive Editing Versus Technical Editing: How Law Review Editors Do Their Job - https://digitalcommons.law.seattleu.edu/faculty/502