Lead Writer: Kieran Morgan | Peer Reviewer/s: Steve Moss, Felicity Brand | Managing Editor: Kieran Morgan

This chapter focuses on the editing stage and details the levels and tools of editing in technical writing. It outlines the traditional levels of editing while adding specific ones tailored for technical writing. The chapter emphasizes the iterative nature of editing and the importance of various inputs, such as style guides and dictionaries. It also discusses the use of artificial intelligence in editing and provides practical steps for the editing process to ensure that documents are clear, consistent, and accurate.

Who Should Read This
• Aspiring Technical Writers • Beginner Technical Writers • Cross-Domain Professionals
Table of Contents: Technical Writing Process
Previous: Chapter 18: Include Images	Next: Chapter 20: Review Draft

1. Introduction

So, you think you’ve written the perfect first draft. You’ve diligently applied the principles outlined in Chapter 18: Writing Principles, and followed the guidance in Chapter 19: Write Draft. You’re eager to send your first draft for review, allowing subject matter experts to validate its accuracy and provide feedback on its effectiveness.

But wait! Don’t rush to send it off without a thorough edit, or you risk looking unprofessional. An unedited document riddled with errors can portray you as careless or, worse, uninformed. It could waste others’ time picking up mistakes you should have already attended to. As technical writers, we’re expected to exhibit expertise in both writing and editing, and abundant attention to detail. Demonstrate your skills by sending a well-edited document for review to showcase your commitment to your craft.

What exactly is editing? It’s the time-honored process of refining a document to reach its final draft stage, when it’s ready for publication. Editing typically involves multiple rounds of review at varying levels. The goal of editing is to ensure that your document is as clear, consistent, and accurate as possible. As discussed in the previous chapter, Chapter 19: Write Draft, editing is an integral part of the write-review-update cycle. Each update to a document requires editing to maintain the quality and structural integrity of the overall work.

Editing relies on two key tools: the Editing Checklist Template and the Editing Sheet Template, as discussed in Chapter 21: Edit Drafts | 3. Editing Tools. It also depends on various inputs like style guides and dictionaries, which we explore in Chapter 21: Edit Drafts | 4. Editing Inputs. The practice of editing itself demands a keen eye for detail and a nuanced understanding of meaning, as explained in Chapter 21: Edit Drafts | 5. [Practice] Edit Draft.

The stage that follows editing is the review process, which we’ll explore in Chapter 22: Review Draft.

Tip

Use Artificial Intelligence (AI) to Save Time in Editing To save time in editing these days, you can use AI tools, AI-assisted checkers like Grammarly, or “prose linters” if you’re working in a docs-as-code environment. Even ChatGPT does a decent job of editing. So, why bother learning about editing? Isn’t it somewhat passé now? Well, no. There are aspects of editing that AI won’t help you with, such as validation, compliance checking, and layout and formatting. These stages are critical for technical writers. It’s also important that you understand the concepts and terminology of editing. Doing so will enable you to work more effectively with AI tools. You can incorporate the levels of editing into your prompts, and a tool like ChatGPT will understand the difference between a structural edit and proofreading, for example. Finally, remember that these tools are far from perfect. You still need to carefully review their output. See Chapter 8: Artificial Intelligence (AI) for Technical Writers for more information.

What Does That Mean?

Prose Linter A tool or software application designed to analyze written text for style, grammar, syntax, and sometimes even content consistency. These tools go beyond spell checkers by offering a more in-depth analysis of the text. The concept is borrowed from the world of programming, where a “linter” is a tool that analyzes source code to flag programming errors.

2. [Theory] Levels of Editing

Editing is traditionally divided into three levels: structural editing, copy editing, and proofreading.¹ To these levels, we’ve added several others that we consider essential for technical writers: validation, compliance checking, and layout and format checking. The addition of these levels ensures that your document isn’t just well-written; it meets all the requirements generally considered essential for publication as a technical document.

As you develop and mature your draft document, you’ll find yourself moving from left to right through the levels of editing. You’ll notice that there’s some overlap between the levels; for example, both proofreading and copy editing involve spelling and grammar checks. This is intentional. Editing is an iterative process involving numerous back-and-forth passes, and there is no hard-and-fast rule on exactly what falls into each level of editing or even how many levels exist.

The levels of editing framework we’ve defined has been tailored specifically for technical writing while drawing on traditional, well-understood editing concepts and terminology. It utilizes two tools at various levels: the Editing Checklist Template and the Editing Sheet Template, which we’ll discuss next.

Insight

Tech Writers Wear Many Hats In most small- to medium-sized organizations, the technical writer often assumes multiple responsibilities or “hats,” such as writer, editor, and designer. In contrast, very large organizations may support specialized or dedicated roles, such as technical editors and designers who handle the layout. You never know where you’ll end up as a writer, so it’s useful to develop a well-rounded skill set.

2.1. Structural or Substantive Editing

Structural or substantive editing is an in-depth analysis of a document’s approach, structure, and coherence. It evaluates whether a document meets its goals and aligns the editing to these objectives. Structural editing may involve a substantial reorganization of the document or a change in approach.

It focuses on:

• Approach: The writer’s general approach to solving the challenges presented in the Documentation Plan is reviewed. This involves placing the document in context and asking challenging questions such as: Is this document fit for purpose? Is it written appropriately for the defined audiences, and does it adequately address the issues they face? Is the use of language, including tone and narrative point of view, appropriate? Are there any weak points? Does the document succeed overall?
• Structure and coherence: This part of the review ensures that the document progresses logically. It checks that context is provided in the appropriate places (such as overviews, introductions) and that each section and topic flows naturally to the next. Navigational elements and components, such as tables of contents, indexes, and appendices, should be considered, as well as structural elements within the content, like cross-references, hyperlinks, callouts, and the use of tables.
• Completeness and relevance: It’s important to also check for completeness (everything necessary has been covered) and relevance (all included information is required in the document).

When to Use: Early in the writing process to set a strong foundation for the document. Midstream in the writing process when integrating or reworking new content into an existing document.  

Insight

When Substantive Editing Becomes a Rewrite Sometimes you’ll find yourself going well beyond substantive editing. You may discover that the material you’re working from is so unfit for its intended purpose that you’re rewriting every sentence, resulting in an end product that bears almost no resemblance to the original. This scenario is common. It can occur when subject matter experts with varying writing skills hack together a document, leaving it to you to refine. This presents a unique challenge for you as the writer to use your writing skills to create a coherent document while preserving the original’s meaning. In such cases, you’ll be drawing once again on the writing skills we discussed in Part 6: Write to collaborate closely with the subject matter experts to ensure your revisions don’t lose any vital details.

2.2. Validation and Testing

Validation and testing is an essential step in ensuring the accuracy of technical documentation, as discussed in detail in Chapter 23: Validate and Test Information. Consider it non-negotiable!

To summarize, it involves two aspects:

• Factchecking: This process involves verifying technical facts against specifications data and reference documentation, or with key subject matter experts. For instance, you might confirm that a range of values described in a product’s user guide matches those in the product specifications.
• Testing: During testing, the writer attempts to follow the steps in the document to verify that they produce the described result or works alongside a subject matter expert to do so. This also includes validating that any text or images from the product’s user interface reproduced in the documentation match the product exactly.

When to Use: Shortly after a topic is written. This step ensures the technical accuracy and practical applicability of the content, which is essential before proceeding to more detailed editing stages and review.

2.3. Copy Editing

Copy editing is an in-depth review of a document’s language, spelling, and grammar. The emphasis is on adding value by analyzing the use of language, its effectiveness for the target audience, and alignment with your organization’s brand guidelines.

In copy editing, language is checked for readability, consistency, and coherency:

• Readability: assessing the reading level, whether subjectively (using your own judgement) or by using a formula (such as Flesch-Kincaid). Readability formulas analyze word length, sentence structure and length, paragraph size, document length, and so on to provide an overall readability score—an approximation of how easy the text is to read.
• Consistency: checking that the same phrases are used to describe identical steps or actions (particularly important when editing for translation) to ensure that key terms are consistently spelled and capitalized, technical jargon is defined, and writing principles are consistently applied.
• Coherency: ensuring that the text flows logically and smoothly. This includes checking for clear transitions between paragraphs and sections, maintaining a consistent tone and style throughout, and verifying that all parts of the document support the overall message and purpose.

When to Use: Toward the end of the writing process but before the review and incorporation of feedback. This stage focuses on language, spelling, and grammar, which are elements best refined once the content’s structure and technical accuracy are established.

Note

Readability Formulas Readability formulas can be misleading. If you’re documenting subject matter that uses long and multisyllabic (but familiar or easily understood) words, such as “telecommunications,” the readability score may appear poor even though its audience might be fine with it. Readability formulas usually prefer short words and can give a false impression that fragmentary sentences are easy to understand.

Note

Editing for Translation Another aspect of editing involves preparing documents for translation, if they are to be translated. Documents destined for translation before publication are edited with particular rigor that focuses on simplification. This approach is designed to make the translation process less time-consuming and expensive (fewer words are more cost-effective) and to reduce the likelihood of terminology causing problems for the translators. For more on this, see Part 9: Translate.

2.4. Compliance Checking

Compliance checking involves verifying that content has been written in accordance with any legal, intellectual property, or regulatory and industry standards. These standards may proscribe strict requirements for anything from the correct spelling of another organization’s trademarks to the use of a certain shape and sized warning symbol. Highly regulated industries, such as aerospace and medical, have detailed requirements for elements to be included or displayed in a certain way in technical documentation. These requirements vary from region to region. See the Editing Checklist Template for more information about specific items to look for.

When to Use: Toward the end of the review process but before approval. After confirming the document is well-written and technically accurate, it’s important to ensure it meets legal and regulatory standards.

2.5. Proofreading

Proofreading checks the mechanical aspects of the document without significantly altering the wording. This includes looking at things like spelling and grammar, as well as the consistency of terms and acronyms.

In print publication, this involves an additional step: checking the integrity of the proof (the final version of a document that will be used for printing or publication). In this stage, the proof is compared against the approved final draft to detect any missing pages or sections and to ensure errors haven’t been introduced. This is particularly important if the proof has been laid out by a graphic designer. It’s easy for text to be copied and pasted into the wrong section or for minor typos to be accidentally introduced.

Proofreading is usually performed as the final step before a significant milestone, such as sending out a document for review or publication.

When to Use: As thefinal check before approval and publication. This step focuses on the mechanical aspects and the integrity of the document, which should be the last line of defense against errors.

2.6. Layout and Format Checking

Checking layout and formatting is often lumped together with proofreading, but it’s important to call it out as a separate category because it can be quite involved in technical writing. It’s the final step before publication, following proofreading.

In this step, the goal is to ensure that the correct template has been applied; that the styles in the template have been correctly applied to the appropriate elements in the text; that navigational elements such as hyperlinks and tables of contents are functioning properly; and that the appropriate branding elements are in place, for example, the correct version and placement of the organization’s logo.

This step also involves checking for any tool-specific issues that arise with particular software packages, such as updating dynamic fields in Microsoft Word. These checks vary depending on the tool used and the final format of the document, such as whether it will be viewed on mobile or desktop platforms. This step can be quite time-consuming, but it’s essential to get it right. If users can’t view your documents due to a formatting issue, all your hard work may come to naught.

When to Use: The last step before publication. This stage is critical for ensuring that the document is not only error-free but also presented in an accessible and professional manner that aligns with the intended guidelines.

3. [Theory] Editing Tools and Inputs

During the editing process, writers rely on several key tools and a variety of inputs. This section explains what these tools and inputs are, and how to use them effectively in your editing.

3.1. Editing Tools

The table below explains the key tools used during editing.

Resource	Description
Editing Checklist	A list of common checks that writers should undertake when editing and proofreading technical documents. Its use ensures documents undergo a rigorous and consistent quality-assurance process prior to publication. Our Editing Checklist Template describes checks applicable to each level of editing. You can customize it to suit your own projects.
Editing Sheet	A list of editorial notes that helps maintain consistency in style and terminology within and across documents, saving you from having to revalidate terms every time you encounter them. This list captures any style decisions made during the editing process. Items commonly found in an Editing Sheet include correctly spelled, punctuated, and capitalized acronyms, technical jargon, product names, user interface elements, trademarks, and role names. Our Editing Sheet Template can be customized and used as the basis for your project. Also known as an editing stylesheet within traditional publishing, we avoid this term here due to the potential for confusion with visual stylesheets, which are discussed in Chapter 16: Design Stylesheet.

3.2. Editing Inputs

During the editing process, you’ll need to keep a number of resources close at hand. Here are some of the typical resources required during editing:

Resource	Description
Style Guide	Guidelines on grammar, punctuation, layout, formatting, structure, and other stylistic aspects of writing. Guidance varies from country to country, so make sure you’re using the correct style guide for your primary audience. An example of a commonly used style guide is the venerable Chicago Manual of Style, published by the University of Chicago Press, widely used in the United States.
House Style Manual	An organization-specific style guide. A house style manual contains guidelines for writing in the organization’s style, including dos and don’ts, instructions for referring to the organization’s trademarks and products, standard legal boilerplate, and the appropriate tone. Although house style manuals usually adhere to general style guides, they often include more specific writing guidelines to address particular organizational preferences.
Technical Writing Style Guide	A publicly available style guide for technical writers referencing or documenting an organization’s products. Large technology companies such as Google, Microsoft, and Apple have style guides tailored to their own products. These guides specify how to refer to user interface elements in their products, among other details. They’re designed to foster consistency and alignment with an organization’s brand. A well-known example is the Microsoft Writing Style Guide.
Industry-Specific Style Guide	A guide that contains rules for a particular industry, such as medicine, journalism, law, or academia. These may be globally or regionally accepted guidelines, depending on the industry. Not all industries have their own style guides, but it’s something you need to verify if you’re new to the industry. One example is the Publication Manual of the American Psychological Association (APA Style Guide). This style guide is widely used in the fields of psychology, education, and other social sciences.
Brand Guidelines	An organization-specific guide focusing on the consistent application of the organization’s brand across documents, usually with an emphasis on visual design. The brand guidelines typically mandate the use of organizational templates and explain the dos and don’ts for logos, colors, fonts, and so on. They commonly also cover writing aspects, blurring the line between house style and brand guidelines. Brand guidelines usually originate in the marketing department. When writing online content, such as help articles, features like fonts, colors, copyright messages, trademarks, and logos need to closely follow brand guidelines.
Dictionary	A dictionary is essential for checking spelling. In most cases, the spellchecker on your authoring tool will suffice. Ensure the language is set to the appropriate location, and be aware of the differences between regions. For example, British English differs from American English. Read more about writing for your geographic audience in Part 9: Translate.
Access to the Internet	You’ll need access to the internet to check the correct capitalization and spelling of company names and trademarks, and to perform basic factchecking.

Note

What to Do If the Guidelines Conflict Style guides are hierarchical, proceeding from the specific to the general. This means when you’re editing, if there’s an ambiguity or conflict, always prefer the more specific style guide, such as a house style manual or brand guidelines. The more general guidelines, such as the Chicago Manual of Style, act as a catch-all for rules not included in the more specific ones.

4. [Practice] Edit Draft

The steps below explain the process of editing a draft document.

4.1. Step 1: Determine the Level of Editing Needed

As you develop and mature your draft, you’ll edit your document multiple times, making numerous passes to refine and polish the content. During this process, you should find yourself moving from the more substantial levels of editing on the left of the Levels of Editing diagram to the finessing stages on the right.

The number of editing cycles you undertake depends on the level of rigor required for the document. Some documents naturally require a higher degree of polish, such as those that will be commercially printed, as well as any documents visible to your organization’s clients or external stakeholders. Documents intended for use by internal teams may not demand the same level of rigor. Nevertheless, remember that every document you write is a reflection of your skills as a technical writer.

Remember, editing is an iterative process. Even when your draft is mature, you may find yourself making unanticipated updates for example, integrating a significant chunk of new material due to a new feature that’s been added at a late stage. In this event, you’ll find yourself moving back to the left-hand column in the Levels of Editing. You may need to give the new content a substantive edit, validate it for technical accuracy, and then structurally review the entire document to ensure the new content integrates well.

Insight

Maximizing Review Efficiency through Proofreading Remember, a well-edited document respects the time your colleagues set aside for document review. To build lasting professional relationships, you should do everything you can to make good use of that time. A poorly proofed document becomes a distraction, as your review team members will stumble over typos, ambiguous wording, and other issues, rather than focusing on the accuracy of the content.

4.2. Step 2: Apply Inputs

While you’re editing, keep your inputs handy, especially your style guide. These will guide you in applying style, punctuation, grammar, and tone during editing. When applying the rules, start with the most specific and proceed to the most general. A rough order of precedence is: Brand Guidelines > House Style Manual > Industry-Specific Style Guide > General Style Guide. (The “>” symbol indicates “takes precedence over.”)

4.3. Step 3: Utilize Tools

As you edit, you should draw on your editing tools: the Editing Checklist and Editing Sheet. Both have different, yet equally important, roles:

• Editing Checklist. Use the Editing Checklist Template to remind yourself of the types of checks to perform at each editing level. Customize it for your project. Over time, with practice, these checks will become second nature, and you’ll likely not need to refer to it as often. However, it’s a useful reminder to ensure nothing is missed, especially when producing multiple smaller documents or topics.
• Editing Sheet. As you edit your document or set of documents, use the Editing Sheet Template to record any editing notes you’ve made during the process. This can include correct spellings of trademarks, product names, user interface elements, role names, technical terms, and so on—anything you’ve invested time and effort in researching and validating. Maintaining a list of these elements ensures consistency within and across documents and saves you from repeatedly validating the same details. It can also become a valuable resource to be shared with the writing team.

4.4. Step 4: Review Draft

Finally, when you’re satisfied that your document has been thoroughly edited and polished, it’s ready for review by subject matter experts, and perhaps your peers as well. This ensures that it is technically accurate and meets expectations. We discuss the nuances of review in the following chapter: Chapter 22: Review Draft.

5. [Template] Editing Checklist Template

Editing Checklist Template

6. [Template] Editing Sheet Template

Editing Sheet Template

1. The Chicago Manual of Style, 17th ed. Chicago: University of Chicago Press, 2017. https://doi.org/10.7208/cmos17. ↩︎