The Technical Editing Workflow: Style Guides, Reviews, and Consistency at Scale
Writing gets the first draft onto the page; editing is what makes it usable. Yet editing is the step most often skipped under deadline pressure, and it is where the difference between amateur and professional documentation becomes obvious. A disciplined editing workflow catches the ambiguous instruction, the inconsistent term, and the missing prerequisite before a reader does — and it does so systematically rather than by luck. Among technical writing best practices, a repeatable editing process is what lets a team produce consistent quality even as the doc set and the roster of contributors grow.
This article lays out editing as a workflow, not a vibe. We cover the levels of edit, how to adopt a style guide without bikeshedding, how to run reviews that actually improve the content, and how to automate the mechanical checks so human reviewers can focus on meaning. If you want the foundations first, see our beginner's guide to technical writing, and pair this with our article on writing for clarity for the sentence-level techniques editors apply.
The Three Levels of Editing
Professional editors work at three distinct altitudes, and confusing them wastes everyone's time. Developmental editing addresses structure and completeness: is the right content here, in the right order, aimed at the right audience, with no gaps or redundancy? Copy editing addresses correctness and consistency: grammar, terminology, style-guide adherence, and formatting. Proofreading is the final pass for typos and broken links. The critical rule is to edit top-down — never polish comma placement in a paragraph that developmental editing is about to delete. Do the structural pass first, the copy edit second, and the proofread last, ideally with a gap between passes so you read with fresh eyes.
Choosing and Adopting a Style Guide
A style guide ends thousands of tiny arguments before they start by making decisions once. You do not need to write one from scratch — adopt an established base and add a short house supplement for your product-specific terms. The Google developer documentation style guide and the Microsoft Writing Style Guide are the two most widely used in software, and both are free and comprehensive. The discipline that matters is not which guide you pick but that you pick one, publish where it lives, and reference it in reviews. Keep your house supplement small and specific: preferred product terms, capitalisation of feature names, and the handful of places you deliberately deviate from the base guide.
Running Reviews That Improve Docs
A documentation review has two jobs that need different reviewers: technical accuracy (is it correct?) usually comes from an engineer or subject-matter expert, while editorial quality (is it clear and consistent?) comes from a writer or editor. Separate these explicitly so an SME is not distracted by comma splices and an editor is not blocked on verifying an API response. Make reviews low-friction: use pull-request review in a docs-as-code setup so comments attach to specific lines and the diff shows exactly what changed. Give reviewers a short checklist and a deadline, and treat the review as feedback on the content, never on the person. The best reviews test the instructions by actually following them, catching the missing step that reads fine but does not run.
Automating Consistency with Linters
Humans are poor at catching mechanical inconsistency across hundreds of pages, and they resent being asked to. Automate it. Prose linters such as Vale let you encode your style guide as rules — flagging passive voice, banned words, inconsistent terminology, and heading capitalisation — and run them in your continuous-integration pipeline on every commit. This shifts style enforcement left, so writers get instant feedback before a reviewer ever sees the draft, and it keeps human reviewers focused on meaning rather than mechanics. Add link checkers to catch broken references and a spell checker with a custom dictionary for your product terms. The payoff compounds: the linter never gets tired, never plays favourites, and documents your standards as executable rules.
Terminology and Voice at Scale
When many people contribute, terminology drifts and voice fragments. Combat this with a maintained terminology list — one approved term per concept, plus the deprecated variants to avoid — enforced partly by your linter and partly by review. Voice is harder to automate but can be codified: document three or four adjectives that describe your desired tone (for example, direct, warm, precise) with before-and-after examples, so new contributors have a target. Consistency of voice is what makes a doc set feel authored by one confident hand rather than assembled by a committee, and readers trust the former far more.
Closing the Loop with Reader Feedback
The final editor is the reader. Add a lightweight "Was this helpful?" widget and analyse the pages that score poorly or generate the most support tickets — those are your editing priorities, ranked by real-world impact rather than guesswork. Review search queries that return no useful result to find the content that is missing or mislabeled. Treat this feedback as a continuous editing backlog. To build a repeatable editing practice for your team, our Technical Editing and Style course at Darlo Technical Writing takes you through all three edit levels on real documents, and includes a downloadable style-guide checklist and a starter Vale configuration you can adapt. Explore the catalogue at /courses. For community-tested review practices, the Write the Docs resources are a reliable ongoing reference. See also our guide to structuring technical content for the developmental-edit foundations.
The Documentation Style-Guide & Review Checklist
A two-part checklist covering the essential style-guide decisions to lock down plus a per-page review pass for accuracy, clarity, and consistency — ready to hand to reviewers.
What are the three levels of editing?
Developmental editing addresses structure and completeness, copy editing addresses correctness and consistency, and proofreading is the final typo-and-link pass. Always edit top-down so you do not polish text that a structural edit will delete.
Do I need to write my own style guide?
No. Adopt an established base such as the Google or Microsoft style guide and add a short house supplement for your product-specific terms, capitalisation, and deliberate deviations. What matters is picking one and referencing it in reviews.
How can I keep documentation consistent across many contributors?
Encode your style rules in a prose linter like Vale that runs in continuous integration, maintain an approved terminology list, and codify your voice with example-driven guidelines. Automation handles mechanics so human reviewers can focus on meaning.