Writing Clear Sentences: A Technical Writer's Editing Playbook
Structure gets readers to the right page; sentence craft gets them through it without friction. Once a document is organized around real tasks, the quality of the individual sentences determines whether a reader glides to completion or stalls, re-reads, and gives up. Clarity at the sentence level is a learnable, mechanical skill — a set of moves you apply during editing, not a mysterious talent.
This playbook collects the sentence-level technical writing best practices that professional editors apply almost automatically. They are drawn from established sources like the Google developer documentation style guide and decades of plain-language research. None require literary ability; they require discipline and a willingness to edit ruthlessly. If you are new to the craft, pair this with our beginner's guide to technical writing, and see our piece on structuring documentation for the layer above the sentence.
Prefer Active Voice and Strong Verbs
Active voice names the actor and puts the action up front: "The server validates the token" rather than "The token is validated by the server." It is shorter, clearer about who does what, and easier to translate. Passive voice hides the actor, which is occasionally useful — when the actor is genuinely unknown or irrelevant — but as a default it drains sentences of energy and creates ambiguity about responsibility.
Strong verbs do similar work. Watch for verbs buried inside nouns: "perform a calculation of" should be "calculate," "provide support for" should be "support," "make a decision about" should be "decide." These nominalizations pad sentences and slow reading. A quick editing pass hunting for "-tion," "-ment," and "-ance" nouns paired with weak verbs (make, perform, provide, conduct) will tighten your prose measurably. In instructions specifically, always lead the step with the verb: "Click Save," not "You should now click the Save button."
One Idea Per Sentence
The most reliable clarity fix is limiting each sentence to a single idea. Long sentences fail not because of word count but because they force the reader to hold multiple conditions in memory at once. When a sentence contains two independent actions, a condition and an exception, or a cause and two effects, split it. Readers process a series of short, direct sentences far more easily than one clause-laden marathon.
Conditions deserve special care. "If X, do Y" should always put the condition before the action so the reader knows whether the instruction applies before they read it. Avoid stacking conditions in prose; convert them to a table or a bulleted list when there are more than two. Aim for varied but generally short sentences — many technical style guides suggest keeping most sentences under about 25 words as a soft ceiling, not a rigid rule. The goal is comprehension on the first read, every time.
Manage Terminology With a Glossary
Inconsistent terminology quietly erodes trust. When a document calls the same thing a "user," an "account," and a "member" in three paragraphs, the reader must constantly decide whether these are the same concept. The fix is a controlled vocabulary: pick one term for each concept and use it everywhere. Maintain a glossary — even a simple spreadsheet — listing the approved term, its definition, and terms to avoid.
Controlled terminology matters most for anything the reader will search for or that has a precise technical meaning. It is also the foundation of good translation and search: consistent terms translate consistently and rank consistently. Resist the writerly instinct to vary word choice for elegance; in technical writing, repetition of the exact right word is a feature, not a flaw. Where a term is genuinely new to your audience, define it on first use and link to the glossary entry.
Write Scannable Procedures
Procedures are the workhorse of technical documentation, and they follow a strict form. Use a numbered list, one action per step, in the order the user performs them. Begin each step with the imperative verb. If the step has a condition, state it first ("If you use SSO, skip to step 5"). If a step produces a result the user should verify, state that result after the action so they know they're on track.
Keep explanatory context out of the step itself — a step should be executable at a glance. If a user genuinely needs background before starting, put a short lead-in before the list, not inside step one. Bold the UI elements they interact with and use code formatting for literal input. A well-formed procedure lets a reader execute while barely reading, glancing only at the bolded targets. For the structural decisions around when to write a procedure at all, revisit our guide to documentation structure.
Edit in Passes, Not All at Once
Trying to fix structure, clarity, grammar, and formatting simultaneously guarantees you'll miss things. Professional editors work in passes, each with a single focus. A typical sequence: first a structural pass (is the information in the right order and complete?), then a clarity pass (active voice, sentence length, terminology), then a mechanical pass (grammar, punctuation, formatting), and finally a consistency pass against the style guide.
Separating the passes lets your attention specialize. During the clarity pass you're not distracted by a missing comma; during the mechanical pass you're not rethinking the outline. Reading aloud — or using a screen reader or text-to-speech — is a powerful clarity check, because your ear catches run-ons and awkward phrasing your eye skips. Build in time between drafting and editing where possible; even an hour's distance restores enough objectivity to see your own writing as a reader would.
Adopt a Style Guide
Every decision above becomes far easier when it's settled once, in a style guide, rather than re-litigated in each review. Don't start from scratch: adopt an industry base such as Google's or Microsoft's developer style guide, then add a short supplement for your product's terminology, UI conventions, and edge cases. This gives new writers instant onboarding and gives reviewers an objective standard instead of personal preference.
Automate enforcement where you can. Prose linters like Vale can check your style rules in CI, flagging passive voice, banned terms, and inconsistent capitalization before a human ever reviews the draft — freeing reviewers to focus on accuracy and completeness. If you want a running start, Darlo Technical Writing provides a downloadable editing-pass checklist and a hands-on Technical Editing course that turns these moves into muscle memory through graded exercises on real docs.
Technical Editing Pass Checklist
A layered editing checklist covering structure, clarity, mechanics, and style — run your draft through four focused passes and catch what a single read-through misses.
Is passive voice ever acceptable in technical writing?
Yes, sparingly. Passive voice is appropriate when the actor is genuinely unknown, irrelevant, or when you deliberately want to keep focus on the object rather than the doer. But as a default it hides who does what and adds length, so prefer active voice and reserve passive for those specific cases.
How long should a technical sentence be?
There's no hard limit, but comprehension on the first read is the real goal. Many style guides suggest keeping most sentences under about 25 words as a soft ceiling. More important than word count is limiting each sentence to a single idea and splitting anything that stacks multiple conditions or actions.
Should I vary my word choice to avoid repetition?
No — in technical writing, repeating the exact right term is a feature. Use one controlled term per concept and use it consistently everywhere. Varying vocabulary for elegance forces readers to decide whether the different words mean different things, which harms clarity, search, and translation.