Editing
Editing is a vital aspect of the technical writing process. It ensures technical documents are accurate, consistent, clear, and comprehensive. You can check for organization, navigation, paragraph structure, style, tone, and overall content, while editing.
Everyone can write, but what makes a valuable document is its conciseness and correctness. Your documentation must be edited to fit all required criteria Such as style, tone, audience needs, and more.
Robert Cormier says - “The beautiful part of writing is that you don't have to get it right the first time, unlike, say, a brain surgeon. You can always do it better; find the exact word, the apt phrase, the leaping simile."
Editing is the layer that makes your technical documentation better.
In this module, you will learn:
- The importance of editing,
- The different types of editing, and
- How to edit for:
- Clarity
- Conciseness
- Correctness
Benefits of Editing
Editing is an essential step in the documentation process for several reasons. It ensures clarity, conciseness, and accuracy in a technical document. We will explore this aspect in details in the coming sections of this module.
1. Error Prevention and Correction
Editing ensures meticulous proofreading to identify and correct errors in grammar, spelling, punctuation, and technical details. Documentation must be error-free to maintain credibility.
2. Consistency in Style and Terminology
Editing ensures consistent terminology, style, and formatting throughout the document. Consistent language helps readers understand and interpret technical information, reducing the risk of confusion or misinterpretation.
3. Alignment with Standards and Guidelines
Organizations have specific standards and guidelines for technical documentation. Editing ensures the document aligns with these standards. It aids compliance and adherence to the organizations' regulations.
4. Enhancement of Readability and Accessibility
Editing involves breaking down complex ideas into digestible pieces, using appropriate headings and subheadings, and incorporating visual elements. Enhanced readability makes technical content more user-friendly for a diverse audience.
5. Logical Organization of Information
Technical editing involves assessing the document's structure and organization. Editing ensures a logical arrangement of information, following a clear and coherent flow. A well-organized document facilitates efficient information retrieval and supports the reader's understanding of complex concepts.
The coming section talks about the various aspects of editing.
Different types of editing
Fig 1: Different types of editing
Ernest Hemingway says - "The first draft of anything is shit." These emphasize the importance of the editing process in refining initial drafts; there are different kinds of editing in some technical documentation.
You may use all the methods for one documentation. In others, you may pair one of each to meet your editing goals.
This section explores proofreading, copy editing, and substantive editing.
Proofreading
Proofreading focuses on finding and correcting errors within writing, grammar, tense, language, typography, spelling, and punctuation. It is carefully examining your work for any remaining mistakes. With proofreading, it is important to slowly and carefully read through your work.
How Proofreading Works
1. Identifying and Correcting Typos
The primary objective of proofreading is to find and correct typographical errors or "typos" in the document. It includes instances where you omit or duplicate letters and words. You go through the document to spot and rectify such mistakes.
2. Checking for Spelling Errors
Spelling errors are common in technical documentation and weakens the credibility of the content. Proofreading involves carefully reviewing the document to identify and correct any misspelled words. It includes common words and industry-specific terminology.
3. Correcting Grammatical Mistakes
Proofreading involves the correction of grammatical errors. It includes issues such as, subject-verb agreement, verb tense consistency, pronoun-antecedent agreement, and sentence structure. Proper grammar is essential for clear and effective communication.
4. Addressing Punctuation Issues
Correct punctuation gives clarity to technical documentation. Proofreading ensures punctuation marks such as commas, semicolons, colons, and periods work correctly. They also check for consistent formatting with quotation marks, parentheses, and other special characters.
5. Cross-Referencing and Hyperlinks
You have cross-references and hyperlinks to related sections or external resources. Proofreading reviews these elements to ensure they are helpful and functional. Broken links or incorrect references disrupt the reader experience and undermine the document's credibility.
6. Formatting and Layout
Proofreading involves paying attention to your document's formatting and layout, including issues like line spacing, margins, and alignment. They ensure the document is visually appealing and adheres to any formatting guidelines.
7. Consistency in Abbreviations and Acronyms
Proofreading involves verifying that abbreviations are consistently applied throughout the document and are defined or explained upon first use.
Example of proofreading
Original:
The studnet's preformance on the experiment was exceelent, demnstrating a thorough understandng of the scientific methode.
Proofread Version:
The student's performance in the experiment was excellent, demonstrating a thorough understanding of the scientific method.
Notice how (student's), (excellent), and (demostrating) were wrongly spelt in the orginal.
It is important to note that proofreading needs a keen eye for detail, a strong command of language, and a thorough understanding of the subject matter. While proofreading can enhance the overall quality of technical documentation by eliminating surface-level errors, it is just the first step in the editing process.
Subsequent editing stages, such as copy and substantive editing, focus on more comprehensive aspects of the document, such as content clarity, style, and overall structure.
Copy Editing
Copy editing involves shaping the technical documentation. It:
- Ensures factual and stylistic consistency across the technical document.
- Improves readability
- Improves sentence flow
- Corrects tone inconsistencies.
Copy editing is the aspect of editing that ensures a piece of writing is accurate, clear, and correct. It ensures the document adheres to a specific style guide, maintains a consistent voice, and presents technical information in a manner that is accessible and engaging for the target audience.
How Copy Editing Works
1. Style and Consistency
Copy editing enforces a consistent style throughout the document. It includes ensuring elements such as headings, subheadings, font styles, and formatting adhere to a predefined style guide (industry standard or organizational guideline).
2. Tone and Voice
Copy editing focuses on maintaining a consistent tone and voice throughout the document. It ensures the documentation tone aligns with the audience expectations. The tone for technical documentation is usually formal and informative, but may need to be adjusted to fit the specific audience.
3. Eliminating Redundancy
Redundant information clutters technical documentation.
Esther Freud says - “Editing is everything. Cut until you can cut no more." Copy editing helps you trim excesses and refine your work to its essential components. You identify and eliminate unnecessary repetition or redundant content to ensure the document is concise.
4. Conciseness and Efficiency
Copy editing makes documentation more concise by removing wordiness and unnecessary tenses. Concise writing is essential for maintaining readers interest and conveying information efficiently.
5. Sentence and Paragraph Structure
Copy editing evaluates sentences and paragraph structure to ensure information logically flows. It may reorganize paragraphs or suggest changes in the sentence structure to enhance the overall coherence of the document.
6. Visual Elements
Copy editing reviews visual elements such as tables, figures, diagrams, and captions to ensure correct labeling, format, and reference within the text. It also checks if visual elements are consistent with the overall style of the document.
7. References and Citations
If the document includes references, citations, or footnotes, copy editing verifies their accuracy and consistency with the chosen citation style, such as APA, MLA, or a specific industry standard.
Example of copy editing
Original:
The company's marketing strategy is good. They aim to reach a wide audience and their products are superior than others in the market.
Copy Edited Version:
The company's marketing strategy is effective. They aim to reach a broad audience, and their products are superior to others in the market.
Notice how copy editing fixed the sentence structure and the tone/voice.
Copy editing ensures the document conveys accurate technical information clearly, concisely, and engagingly, enhancing its usability and effectiveness.
Substantive Editing
Substantive editing is a more in-depth and comprehensive stage of the editing process. It involves shaping the consistency, cohesiveness, and conciseness of technical documentation.
Consistency implies ensuring that information presented in diverse parts of the document agrees each other. Take the example of having “producer” and “manufacturer” in the same document Cohesiveness implies ensuring information flows logically.
| logical arrangement | alphabetical arrangement |
|---|---|
| Start | Accelerate |
| Accelerate | Brake |
| Brake | Start |
| Stop | Stop |
Substantive editing checks the intended use, organization, flow, and content strength. You can also check if too much or too little information is present and if similar information is presented consistently across documentation. But it is always better to use less information.
Thomas Jefferson says - “The most valuable of all talents is that of never using two words when one will do."
How substantive editing works
1. Content Evaluation
It evaluates the overall documentation to ensure it aligns with the documentation purpose and target audience. It assesses whether the content is relevant, accurate, and comprehensive.
2. Structural Reorganization
It involves reorganizing the document's structure for optimal clarity. You suggest changes to the order of sections, headings, and subheadings to ensure a logical flow of information. This restructuring makes complex technical concepts more accessible to readers.
3. Content Expansion or Reduction
Depending on the documentation purpose, substantive editing may recommend adding more detailed explanations or examples for better clarity. Conversely, it might require condensing overly thorough content to maintain conciseness while preserving essential information.
4. Tone and Voice Adjustment
It fine-tunes the documentation tone and voice. It ensures the content is better pitched for end-users, technical experts, or other stakeholders. The adjustment helps maintain the reader's engagement.
5. Enhancing Clarity
It makes the technical content clear, rephrases sentences, and simplifies complex language. The goal is to ensure readers with limited technical knowledge grasp the information.
6. Fact-Checking and Accuracy
It pays meticulous attention to the accuracy of the information presented. Substantive editing verifies data, statistics, references, and technical details to ensure they are up-to-date and accurate. The fact-checking is essential for maintaining the documentation’s credibility.
7. Consistency in Terminology
It confirms that terminology and technical jargon work consistently throughout the documentation. It may create a glossary to define all technical terms and ensure the definition or explanation of the terms upon first use.
8. Cross-Referencing and Citations
It checks the accuracy and consistency of cross-references, citations, and footnotes. Substantive editing ensures correct formatting of all references according to the chosen citation style, such as APA, MLA, or a specific industry standard.
9. Visual Elements
Substantive editing reviews and suggests improvements to visual elements, such as tables, figures, diagrams, and captions. It confirms if these elements enhance the content's clarity and integrate effectively into the text.
10. Usability and Accessibility
It considers the usability and accessibility of the document. It includes assessing its navigational aids, such as headings, bulleted lists, and links, to ensure readers easily find information. This improves accessibility of the document to individuals with disabilities in compliance with relevant accessibility standards.
Example of substantive editing
Original:
In this report, we discuss various aspects of climate change. The first section is about causes, the second is about effects, and the third is about solutions.
Substantive Edited Version:
This report comprehensively explores climate change, covering its causes, effects, and potential solutions in three distinct sections.
Notice how substantive editing fixed the overall structure, organization, and content.
Substantive editing is a critical step in producing high-quality technical documentation. It ensures the documentation communicates accurate technical information but does so in a way that is clear, well-structured, and tailored to the needs of the intended audience, ultimately enhancing its value and impact.
In the next section, you will learn how to edit technical documentation for clarity, conciseness, and accuracy (correctness).
Editing Technical Documentation for Clarity, Conciseness, and Correctness (Accuracy)
Fig 2: Different stages of editing
Editing for clarity, conciseness, and correctness is a standard for producing credible and quality technical documentation. The section details how to edit technical documentation with the 3Cs.
Clarity
Clarity refers to the quality of being clear, transparent, and easily understood. It involves expressing ideas, information, or instructions in a way that is easy for the audience to comprehend. A clear message is free from ambiguity, confusion, or unnecessary complexity. Editing for clarity ensures easy understanding for its target audience.
How to Edit for Clarity
1. Understand Your Audience
Before you begin the editing process, clearly understand your target audience. Are you writing for technical experts, beginners, or a mixed audience? Knowing your audience knowledge level, interests, and expectations is the first step in editing for clarity.
2. Simplify Technical Jargon
Technical documentation often contains specialized terminology and jargon unfamiliar to non-experts. Edit by explaining technical terms and consider using simpler synonyms. Clarity helps you strike a balance between technical accuracy and accessibility.
3. Organization and Structure
Review the organization and structure of the document. Ensure that information is logically presented. Use Headings and subheadings as it helps readers navigate through your content. Group related information and use a clear hierarchy to show the relationship between sections.
4. Consistency
Consistency in terminology, style, and formatting is essential for clarity. Ensure the consistent use of the same terms throughout the documentation. Formatting elements such as fonts, headings, and lists should follow a uniform style.
5. Active Voice
Sentences written in active voice are more direct and easier to understand. Passive voice may make sentences more complex and less clear. To improve clarity, ensure your sentences use active voice.
6. Avoid Ambiguity
Ambiguity can lead to confusion. Review your content for ambiguous terms, phrases, or sentences. Be explicit in your explanations, and avoid leaving room for multiple interpretations. If there's room for misunderstanding, clarify.
7. Visual Aids
Consider using visual aids like diagrams, charts, and illustrations. These help clarify complex concepts and make the content more accessible. Ensure proper labeling of visual aids and integration into the text.
8. Examples and Analogies
Provide real-world examples and analogies to explain technical concepts. Analogies bridge the knowledge gap and make abstract or complex ideas more relatable.
9. Revision and Iteration
Editing for clarity is an iterative process. After making initial edits, revisit the document multiple times to refine and enhance its clarity. Each revision brings the content closer to your clarity goals.
Original:
The new software update has implemented changes to the user interface, providing users with a more seamless and user-friendly experience.
Clarity Edit:
The latest software update has improved the user interface, making it more seamless and user-friendly.
Notice how clarity edit gave better understanding and easy readability to the text.
By applying these principles and techniques, you can effectively edit technical documentation for clarity, making it more accessible and understandable for your intended readers, regardless of their level of technical expertise. Clarity in technical documentation is vital to its usability and effectiveness.
Conciseness
Conciseness refers to the quality of expressing ideas in a precise manner without unnecessary elaboration or redundancy. Concise technical documentation conveys information using the most efficient/effective language, avoiding unnecessary words or details that do not contribute to the main message.
Editing for conciseness is also an essential aspect of creating better technical documentation. A concise document is more engaging, easier to read, and communicates information more efficiently.
How to Edit for Conciseness
1. Identify Redundant Information
Review your document to identify redundant content. Check for repeated information, ideas, and unnecessary phrases and eliminate redundancy to make the document more concise.
2. Remove Unnecessary Words
Carefully examine each sentence and paragraph to identify and remove unnecessary words. Examples include filler words, redundant adjectives, and overly complex sentence structures. Simplify sentences to convey the same meaning, but with fewer words.
3. Avoid Wordiness
Check for wordy phrases you can shorten without losing meaning.
For example, replace
- "due to the fact that" with "because"
- "in order to" with "to."
Reducing wordiness is a quick way to increase conciseness.
4. Use Active Voice
Passive voice sentences are wordier than active voice sentences. Rewrite passive voice sentences to make them active. It shortens sentences and makes them direct and engaging.
5. Cut Down on Qualifiers
Qualifying words and phrases like "very," "extremely," "quite," and "somewhat" can be eliminated without affecting the meaning of a sentence. Reducing qualifiers leads to more concise and assertive statements.
6. Condense Lists
Lists may become lengthy and cumbersome. Edit lists to be more concise by:
- Removing unnecessary items
- Combining related items
- Using table or chart
7. Use Abbreviations and Acronyms Judiciously
Abbreviations and acronyms help reduce the length of technical terms. However, carefully use them and ensure it suits your target audience. Always spell out the full term on first time and include the abbreviation in parentheses.
An example is the Technical Writing Mentorship Program (TWMP)
8. Focus on Key Information
Prioritize the most critical information and eliminate less vital details. Your documentation should deliver the essential information without overwhelming the reader.
9. Use Bullet Points and Headings
Bullet points and headings can break up dense paragraphs and provide concise, organized information. Use them to present key points and create a visually appealing document.
10. Example of Editing for Conciseness
Original:
It is important to note that the primary reason for the increase in sales is due to the fact that our marketing strategies have been highly effective.
Conciseness Edit:
The increase in sales is primarily due to our highly effective marketing strategies.
Notice how concise edit eliminated unnecessary words/information and made the content more direct.
Editing for conciseness is a better balance between preserving essential information and removing unnecessary content. A concise document saves the writer and the reader time and enhances the documentation overall readability and impact.
Correctness (Accuracy)
Correctness refers to the quality or state of being accurate, and following established standards, rules, or facts. In technical documentation, correctness is a measure of accuracy and appropriateness. Editing for correctness is critical in technical documentation. It ensures the information in your documentation is precise and error-free.
How to Edit for Correctness
1. Fact-Checking
Verify the accuracy of data, statistics, references, and any technical details. Ensure the information is up-to-date and consistent with current knowledge and industry standards.
2. Cross-Reference Sources
If your document cites external sources or references, cross-reference these sources to confirm the accuracy of the information. Check that citations are correctly formatted and lead to the intended source.
3. Check Technical Details
Pay close attention to technical details. Double-check codes, calculations, formulas, and specific measurements to ensure accuracy. Even minor errors in technical details have significant consequences.
4. Grammar and Syntax
Accurate grammar and syntax are essential for clear and precise communication. Review the document for grammatical errors, such as subject-verb agreement, verb tense consistency, and sentence structure. Incorrect grammar can lead to misunderstandings.
5. Check Spelling and Typographical Errors
Even a single typographical error casts doubt on the accuracy of your document. Proofread the document carefully to spot typographical errors. They can change the meaning of a word or term, leading to confusion.
Maintaining accuracy in technical documentation is paramount, as errors lead to misunderstandings, misinterpretations, or potentially dangerous consequences.Thoroughly editing for accuracy helps ensure your document is a reliable and trustworthy source of information.
Example of Editing for Correctness
Original:
The experiment was condcted on April 25th, 2022, and the results were published in the June 202 edition of the journal.
Correctness Edit:
The experiment was conducted on April 25, 2022, and the results were published in the June 2022 edition of the journal.
Notice how correctness edit ensured the document is accurate and free from errors.
Editing improves the quality of your technical documentation, making it a valuable resource that communicates concisely and accurately to your target audience.
Complete the following exercises before proceeding to the next module.
Carefully edit this technical document for all of the diferent types and aspects of editing discussed in this module. After review, tag @TechnicalWriti6 on X(Twitter) with the link to your published submission.
Toggle to preview the content
Growth, an ever-present facet of the human experience, manifests in myriad dimensions throughout our lives. It transcends physicality, weaving into personal development, knowledge acquisition, emotional resilience, and societal progress. As we traverse life's intricate tapestry, growth emerges as our guiding compass through uncharted territories of potential.
Growth is a dynamic process, an intricate dance between aspiration and realization. It encapsulates evolution, a continuous journey unfolding in response to external stimuli, internal reflections, and the interplay of resilience and adaptability. In personal development, growth mirrors a seedling breaking through soil, reaching for the sun, driven by an innate desire to thrive.
The journey of growth often commences in the crucible of challenges. Adversity, far from being an obstacle, serves as fertile ground where seeds of potential sprout and resilience takes root. Challenges are not adversaries but catalysts for growth, urging us to stretch beyond perceived limitations, fostering courage, and fortifying resolve. It is through the crucible of challenges that character is forged, and latent capacities within us unfurl.
Educational pursuits exmeplify transformative arenas for growth. The acquisition of knowledge, skills, and perspectives propels individuals toward intellectual maturity and a deeper understanding of the world. Growth in education is not confined to the classroom; it permeates every facet of life, shaping critical thinking, problem-solving abilities, and a nuanced appreciation for diverse viewpoints.
Beyond personal development, societal growth emerges from collective endeavors to address challenges, innovate, and build a more equitable and sustainable future. Societal growth is a tapestry woven by the collaborative efforts of individuals and communities, each contributing unique threads to the fabric of progress. It encompasses advancements in technology, improvements in infrastructure, and the evolution of cultural norms that reflect an ever-changing collective consciousness.
Economic growth, a pivotal aspect of societal progress, is not merely measured in monetary terms but also in the expansion of opportunities, the reduction of inequalities, and the enhancement of overall well-being. A flourishing economy is one that fosters innovation, embraces diversity, and ensures that the benefits of growth are inclusive, reaching all segments of society.
The dynamisc of growth extend into the intricate realm of emotional and spiritual maturation. Embracing vulnerability, cultivating empathy, and navigating complex landscapes of human relationships contribute to profound personal growth. Emotional resilience, forged through life's trials, enables individuals to weather storms with grace and emerge stronger, more compassionate beings.
In the natural world, growth is evident in the cycles of seasons, where flora and fauna undergo transformations, demonstrating the cyclical nature of life. Trees, with roots delving deep into the earth, symbolize stability, while their branches reaching skyward epitomize the ceaseless pursuit of higher aspirations. Nature, with its intricate ecosystems, teaches us the interconnectedness of growth—a reminder that individual and collective flourishing are intertwined.
The metaphor of growth extends to the corporate landscape, where businesses navigate competitive climates and market fluctuations. Sustainable growth in business involves strategic foresight, adaptability to changing market dynamics, and a commitment to ethical practices. Organizations that prioritize innovation, employee development, and societal responsibility contribute not only to their growth but also to the broader fabric of societal advancement.
Growth, however, is not a linear trajectory but a mosaic of peaks and valleys, successes and setbacks. It necessitates reflection on failures as opportunities for learning and refinement. The willingness to reassess goals, recalibrate strategies, and pivot in response to evolving circumstances is integral to sustained growth.
In the pursuit of growth, the concept of self-discovery assumes paramount significance. Knowing oneself—acknowledging strengths, confronting weaknesses, and understanding one's passions—forms the bedrock for intentional personal and professional growth. This introspective journey fosters authenticity, aligning individual aspirations with actions that propel growth.
As we navigate the myriad dimensions of growth, it is crucial to recognize that the pursuit of progress is not a solitary endeavor. Collaborative growth, where individuals, communities, and societies uplift each other, catalyzes a collective ascent toward shared ideals. Growth becomes not only a personal quest but a shared commitment to building a world that reflects our highest aspirations.
In conclusion, growth is the rhythmic heartbeat that animates the human experience. It is the unfurling of potential, the refinement in the crucible of challenges, and the collective endeavor to create a better world. Embracing the dynamics of growth requires resilience, adaptability, and a steadfast commitment to continuous learning. In this intricate dance of evolution, we discover the profound beauty of becoming—who we are meant to be and who we are continually striving to become.
The next module explores in-depth the use of diagrams in technical documentation.