Technical Documentation Quality Criteria
Regardless of your role—writer, editor, reviewer, or approver—the goal is the same: to create better documentation. But how do you achieve that?
This chapter introduces six essential quality criteria of technical documentation: accuracy, completeness, consistency, clarity, usability, and compliance. These criteria provide actionable benchmarks that guide technical writing, editing, and reviewing to shape high-quality documentation. By applying these criteria, every participant in the documentation process can contribute to precise, clear, and user-friendly documentation.
Quality Assurance and Quality Criteria
Quality assurance in technical writing is an overarching strategy that ensures that documentation meets the highest standards of quality. For quality assurance to be effective, it requires clear, measurable standards–quality criteria to guide the overall process of documentation preparation, to verify that content is free from errors, consistent in technical information, and adheres to established guidelines.
Below are six quality criteria of technical documentation and their definitions:
Accuracy: All technical details in the documentation, including textual descriptions and graphical information, are correct and precise.
Completeness: The information provided by the documentation is complete, including all product’s key features and functionalities, and covering important user tasks and scenarios.
Consistency: Technical descriptions and terminologies are consistent throughout one document, across different document types, and between different languages.
Clarity: The information is clear in meaning and logically organized. The intended audience should find the document easy to understand without ambiguity.
Usability: Documentation is easy to navigate. Information is easy to find.
Compliance: Documentation complies with company policies and style guides.
Six Quality Criteria
This section describes each quality criterion in detail, incorporating examples related to the criterion, case studies from real-world scenarios, and best practices to avoid common issues.
Accuracy
Accuracy is foundational to technical documentation because it ensures that users receive precise and reliable information. Accuracy applies to technical specifications, descriptions, terminology, code samples, and visual content such as diagrams and schematics. Inaccurate documentation can lead to product misuse, operational failures, and a loss of trust from users. By focusing on accuracy during technical writing, editing, and reviewing, you can identify and resolve errors, preventing users from encountering issues.
Examples
Examples of accuracy issues include:
Specifying a component operates at 5 V when it should be 3.3 V, leading to hardware damage.
Swapping the ground and power pins in a schematic, causing miswiring and potential failure.
Using a capacitor symbol to represent an inductor, leading to confusion in design.
Stating that a feature is enabled by setting a register to 1 when it should be set to 0, causing debugging delays.
Providing outdated code samples, leading to failure of using product.
Good Practices
Below are some recommended practices for ensuring accuracy of documentation:
Cross-check between documentation: Cross-check documentation against the latest design specifications, datasheets, and software documentation to ensure it reflects consistent information.
Test the content: If possible, test the content such as code samples, API guides, programming procedures to verify correctness.
Case Studies
In the screenshot below, after reusing the diagram from another document, the Xtensa microprocessor was mistakenly labeled as a RISC-V microprocessor.
Accuracy Issue
This inaccuracy led to customer confusion and complaints. It can be avoided by verifying the information against the design specifications.
Completeness
The completeness criterion is essential for ensuring that technical documentation provides all necessary information to its users. A complete document covers every feature, functionality, and operational step needed for successful use, leaving no critical gaps. When documentation is incomplete, users may face challenges such as product misoperation, confusion about features, or the inability to accomplish key tasks. By addressing completeness during technical writing, editing, and reviewing, you can ensure that no essential information is overlooked.
Examples
Examples of completeness issues include:
Failing to describe a key functionality of the product, leading to limited or improper usage of the product.
Omitting essential setup steps or programming procedures, resulting in unsuccessful product operation.
Excluding a schematic in a board’s user guide, causing hardware design issues.
Leaving out measurement units in data, confusing users when they interpret the information.
Good Practices
Below are some recommended practices for ensuring complete documentation:
Use a checklist or template: Rely on documentation templates or predefined checklists to verify that all necessary sections and information are included.
Test the documentation: Follow the outlined steps and procedures yourself or have them tested to confirm that all instructions are sufficient and no critical details are omitted.
Case Studies
In the screenshot below, the programming procedures for a peripheral are incomplete, as they omit the preceding steps to power up the peripheral and enable clocks.
Completeness Issue
This omission led to customer confusion and operational failure. Such issues can be avoided by adhering to the established template of technical reference manuals.
Consistency
At Espressif, multiple teams contribute to various types of documentation, ranging from hardware manuals to software guides. Maintaining consistency across all these documents is essential to ensure cohesion, prevent confusion, and deliver a unified experience to users. Key aspects of consistency include:
Uniform information within a single document.
Consistent information across related documents.
Alignment between hardware and software documentation.
Standardized terminology throughout the document.
Consistency between English and Chinese versions of the documentation.
Ensuring consistency during technical writing, editing, and reviewing is vital for creating a seamless user experience and reinforcing the credibility and reliability of the documentation.
Examples
Examples of inconsistencies include:
One section advises connecting a component to pin 1, while another advises pin 2.
Diagrams depict layouts that differ from textual descriptions.
A document claims support for Bluetooth LE 5.0, while a related document claims Bluetooth LE 5.3.
Different terms are used to refer to the same component in various sections of one document.
Good Practices
Below are some recommended practices for maintaining consistency of documentation:
Cross-check between documentation: Verify that the information in one document aligns with other related documents to ensure cohesion.
Adhere to a glossary: Use an established glossary or create one if none exists to ensure standardized terminology across all documents.
Refer to prior descriptions: Review earlier sections or related documentation to maintain consistent presentation and details throughout.
Case Studies
In the screenshot below, measurements for the distance between the center of the ground pad and the edge of the module differ when labeled from different perspectives (bottom view on the left, top view on the right).
Consistency Issue
This inconsistency led to customer confusion. Such an issue can be avoided by reviewing previous sections to ensure alignment and uniformity.
Clarity
Clarity is a cornerstone of effective technical documentation. Clear documentation ensures that instructions, explanations, and descriptions are precise, logically organized, and easy to understand. Ambiguous or overly complex information can lead to user misinterpretation, frustration, and errors in product use, which undermines the value of the documentation.
Prioritizing clarity during technical writing, editing, and reviewing enhances the readability of the document. It involves simplifying complex concepts, organizing information logically, and tailoring the content to the audience’s level of expertise. Effective clarity transforms dense, convoluted text into clear, straightforward, and understandable content.
Examples
Examples of clarity issues include:
Instructions for setting up a test environment are not sequentially ordered.
Vague statements such as “This feature may be supported in some cases.”
Using abstract marketing phrasing instead of stating facts.
Complex sentences or technical jargon that impede comprehension for the average user.
Poorly structured content that disrupts logical flow and readability.
Good Practices
Below are some recommended practices for maintaining clarity of documentation:
Simplify language: Use straightforward and concise wording, avoiding unnecessary jargon or overly complicated sentences that could confuse readers.
Organize content logically: Break down information into clearly defined sections, using headings and subheadings to guide readers through the document. Sequence instructions and steps in a logical order.
Define technical terms: Provide explanations for technical terms or acronyms that might be unfamiliar to readers. Including a glossary is especially useful for quick reference.
Add visual aids: Use diagrams, tables, or bullet points to present information in an accessible, easy-to-digest format.
Case Studies
Consider the following original statement:
Soldering the EPAD to the ground of the base board is not a must, however, it can optimize thermal performance. If you choose to solder it, please apply the correct amount of soldering paste.
The phrase “apply the correct amount of soldering paste” is vague and leaves the reader wondering how much is “correct” and why this matters.
A revised version provides more clarity by including specific details:
Soldering the EPAD to the ground of the base board is not a must; however, it can optimize thermal performance. If you choose to solder it, ensure you apply just enough soldering paste to cover the surface. Too much paste may increase the gap between the module and the baseboard, resulting in poor adhesion of other pins.
This version resolves ambiguity by explaining both the consequences of excessive paste and the desired outcome, giving the user clearer guidance.
Usability
The usability criterion ensures that documentation is intuitive, accessible, and easy to navigate. Effective usability minimizes the time and effort required for users to locate and interpret the information they need. When documentation lacks usability, users may struggle to find relevant sections, encounter broken links, or fail to access key details, ultimately leading to frustration and reduced productivity.
During technical writing, editing, and reviewing, focus on usability to refine the structure, navigation tools, and presentation of content, so that the documentation provides a seamless and satisfying experience for the users.
Examples
Examples of usability issues include:
Missing a table of contents in a lengthy or complex document, making navigation difficult.
Broken cross-references or hyperlinks, preventing users from accessing related documents or sections.
Landing on a “404 Not Found” page without any explanation or redirect to relevant content.
Omitting a board user guide from the Documentation page, making it hard for users to locate critical resources.
Using non-searchable text in diagrams, which limits accessibility for keyword searches.
Good Practices
Below are some recommended practices for maintaining usability of documentation:
Provide effective navigation tools: Ensure the document includes an intuitive navigation system, such as a comprehensive table of contents, an index, and functional cross-references. These tools help users quickly locate relevant information.
Simplify content layout: Use bullet points, numbered lists, and headings to break complex information into manageable and skimmable sections.
Emphasize key information: Highlight critical details using visual elements like bold text, callouts, or colored text boxes to draw attention to important content.
Case Studies
In the screenshot below, the mentioned interrupts are not linked to their corresponding descriptions in the document.
Usability Issue
This section could be improved by adding cross-references to link each interrupt to its detailed description. Adding links saves users time and makes the content more accessible.
Compliance
The compliance criterion ensures that documentation aligns with company policies, industry standards, and established style guides. By addressing compliance during technical writing, editing, and reviewing, you safeguard the documentation against regulatory violations, preserve formatting consistency, and reinforce the professional image of the company.
Examples
Examples of compliance issues include:
Misusing the company logo in a way that could harm the company’s image.
Disclosing sensitive customer information in public documentation.
Formatting content inconsistently with the Espressif Manual of Style.
Providing register descriptions that do not conform to the Register Description Conventions.
Good Practices
Below are some recommended practices for maintaining compliance of documentation:
Adhere to style guides: Verify that the documentation follows formatting standards outlined in the company’s style guide.
Protect confidential information: Consult with the audit or legal team to confirm that sensitive data is properly handled and omitted if necessary.
Follow established conventions: Apply template conventions, such as those for register descriptions, to maintain uniformity across technical content.
Case Studies
In the example below, the register description is unclear, incomplete, and fails to meet the conventions for register descriptions:
Compliance Issue (Before)
By adhering to the Register Description Conventions, the description is improved, providing detailed and user-friendly content:
Compliance Issue (After)
Conclusion
To transform raw technical content into clear, accurate, and professional documentation, technical writers, editors, and reviewers need to align their roles with the six key criteria—accuracy, completeness, consistency, clarity, usability, and compliance.
By adhering to the criteria, we ensure that the documentation is precise, comprehensive, and user-friendly. These criteria not only enhance the document’s overall quality but also improve the user experience, making it accessible and aligned with company standards. Together, they empower users to understand and effectively utilize our product or technology.