Writing Sentences Developers Can Act On: Plain-Language Techniques for Technical Docs
Clear communication in technical documentation is not a talent; it is a set of learnable techniques applied at the sentence level. The best documentation reads as though it were effortless, but that ease is engineered—every sentence structured so the reader grasps it on the first pass and can act without re-reading. Among all technical writing best practices, sentence-level clarity is the one with the highest return, because it improves every document you will ever write.
This guide is about the small, repeatable moves that produce clarity: choosing the active voice, using precise verbs, managing sentence length, and structuring instructions so they are unambiguous. These are the habits that separate documentation readers trust from documentation they endure. For the wider context of the craft, start with our beginner's guide to technical writing, then return here for the sentence mechanics.
Why Unclear Sentences Cost More Than You Think
An unclear sentence in a novel costs the reader a moment of confusion. An unclear sentence in technical documentation can cost hours—a developer implements the wrong behavior, an operator misconfigures a system, a support queue fills with tickets that trace back to one ambiguous instruction. Because documentation is acted upon, not merely read, the cost of ambiguity is multiplied by every reader who follows the wrong interpretation.
This is why plain language is a professional obligation in technical writing, not a stylistic preference. Plain language means the reader understands the first time. It does not mean dumbing down; complex ideas can be expressed plainly, and often the effort to do so reveals that the writer did not fully understand the idea themselves. The public guidance at plainlanguage.gov codifies decades of research into concrete techniques, most of which apply directly to technical documentation regardless of industry.
Active Voice and the Right Subject
The single most effective clarity move is choosing the active voice with the actor as the subject. "The system sends a confirmation email" tells the reader who does what; "A confirmation email is sent" hides the actor and forces the reader to infer it. In instructions, the actor is usually the reader, and active voice makes that explicit: "Click Save," not "The Save button should be clicked." Passive voice is not forbidden—it is useful when the actor is genuinely unknown or irrelevant—but as a default it drains sentences of clarity.
Choosing the right subject matters as much as choosing the voice. The subject of a sentence should usually be the thing the sentence is about. When you find yourself writing long chains of nouns—"user authentication token expiration configuration"—the sentence has lost its subject, and the reader has lost the thread. Break the chain, name the actor, and give the verb something concrete to do. The Google developer documentation style guide offers excellent, specific guidance on voice worth adopting wholesale. For the review process that catches these issues, see our guide to editing and review.
Precise Verbs and Concrete Nouns
Weak verbs are the most common source of vague documentation. Verbs like "handle," "process," "deal with," "support," and "manage" tell the reader almost nothing about what actually happens. "The service handles the request" could mean it validates, queues, transforms, rejects, or forwards the request—the reader cannot tell. Replacing weak verbs with precise ones ("validates," "caches," "retries," "discards") is often the fastest way to sharpen a paragraph, and it frequently exposes gaps in the writer's own understanding that need to be resolved before publication.
Concrete nouns do the same work for the objects of your sentences. Abstract nouns like "functionality," "solution," and "capability" are placeholders that let a writer sound informative while saying nothing. Prefer the specific thing: not "the export functionality" but "the CSV export." A useful habit is to hunt for nominalizations—verbs turned into nouns, like "perform a calculation" instead of "calculate" or "make a decision" instead of "decide." Turning them back into verbs shortens sentences and restores energy. These habits reinforce the structural clarity covered in our guide to documentation structure.
Sentence Length and Cognitive Load
Long sentences fail readers not because length is inherently bad but because they exceed working memory. When a reader has to hold three clauses in mind to reach the verb, comprehension drops and re-reading begins. The fix is not to make every sentence short—monotonous staccato is its own problem—but to vary length deliberately and keep the load manageable. Aim for one main idea per sentence, and when a sentence carries a condition, an action, and an exception, split it.
Conditions deserve special attention because they are everywhere in technical writing. "If the token has expired, refresh it before retrying the request" leads with the condition, which is correct—readers need to know the condition before the action so they can decide whether the sentence applies to them. Putting the condition first ("If X, do Y," not "Do Y if X") lets a reader who is not in situation X skip ahead immediately, which is exactly how people read documentation.
Writing Instructions People Follow
Instructions are where clarity is tested hardest, because a reader is executing your words in real time. The reliable pattern is numbered steps, one action per step, each beginning with an imperative verb, in the exact order the reader must perform them. State the result of a step when it is not obvious, so the reader can confirm they succeeded before continuing. Never bury a required action inside a paragraph of explanation—if it must be done, it gets its own step.
Anticipate the two questions every reader of instructions has: "Am I in the right place?" and "Did that work?" Establish the starting context before the first step, and show expected outcomes at key points. Avoid "simply" and "just"—words that trivialize a step and make a stuck reader feel foolish rather than helped. Darlo's Clear Technical Writing course drills these instruction patterns with real before-and-after exercises, and enrolment includes a downloadable plain-language editing checklist you can run over any draft. For deeper study of how professionals refine prose, the resources at Write the Docs are excellent.
Editing for Clarity
Clear writing is mostly rewriting. First drafts capture ideas; editing makes them usable. The most productive editing pass is subtractive—cutting words that carry no meaning. "In order to" becomes "to," "due to the fact that" becomes "because," "at this point in time" becomes "now." Every removed filler word raises the signal-to-noise ratio, and technical readers, who are scanning for the actionable content, feel the difference immediately.
Two techniques catch what silent reading misses. Reading your draft aloud exposes sentences that run out of breath and phrasing that stumbles. Automated tools help too: readability checkers flag long sentences, and prose linters like Vale enforce plain-language rules consistently across a team. But tools only surface candidates—judgment decides. The goal is never to hit a readability score; it is to ensure the reader understands the first time, acts correctly, and never has to read the sentence twice.
The Plain-Language Editing Checklist
A downloadable one-page checklist for editing technical drafts—active voice, precise verbs, filler-word cuts, and condition-first instructions—so any draft reads clearly on the first pass.
Is passive voice always wrong in technical writing?
No. Active voice should be your default because it names the actor and reads more clearly, especially in instructions. But passive voice is appropriate when the actor is genuinely unknown, irrelevant, or when you deliberately want to emphasize the thing acted upon rather than the actor. Use it consciously, not by habit.
How long should sentences in documentation be?
There is no fixed limit, but aim for one main idea per sentence and vary length to avoid monotony. Split any sentence that combines a condition, an action, and an exception. If a reader must hold several clauses in mind to reach the verb, the sentence is too long for comfortable comprehension.
What is the fastest way to make a draft clearer?
Cut filler words and replace weak verbs with precise ones. Change "in order to" to "to," turn nominalizations like "perform a calculation" back into verbs like "calculate," and replace vague verbs like "handle" with what actually happens. Then read it aloud to catch anything that still stumbles.