Active Voice & Short Sentences
Clarity in technical writing comes down to two mechanical habits: use active voice and keep sentences short. These are not style preferences. They are precision tools. Active voice assigns responsibility. Short sentences reduce cognitive load. Together, they produce writing that readers understand on the first pass.
Most unclear technical writing is not unclear because the ideas are complex. It is unclear because the sentences are convoluted. Fix the sentences and the ideas become accessible.
Active Voice Assigns Responsibility
In active voice, the subject performs the action. In passive voice, the subject receives the action. The difference matters because technical writing frequently needs to communicate who does what.
Passive: "The configuration file was updated."
Active: "The deploy script updates the configuration file."
Passive: "Errors were introduced during the migration."
Active: "We introduced errors during the migration."
Passive: "The request is validated before processing."
Active: "The API gateway validates the request before the
worker processes it."
Notice what passive voice hides: the actor. "The configuration file was updated" — by whom? By what? A human? A script? An automated process? The reader has to guess. Active voice eliminates the guessing.
This matters especially in incident reports and post-mortems:
Passive (hides responsibility):
"Mistakes were made in the deployment process. The wrong
configuration was applied to production, and the rollback
procedure was not followed."
Active (assigns responsibility clearly):
"The on-call engineer deployed the staging configuration to
production. The team did not follow the rollback procedure
because the runbook was outdated."
The passive version reads like a politician's non-apology. The active version reads like an engineering team that understands what happened and can fix it. Active voice is not about blame — it is about clarity. You cannot fix a problem if you cannot name who or what caused it.
When Passive Voice Is Acceptable
Passive voice is not always wrong. It has legitimate uses:
When the actor is genuinely unknown or irrelevant:
"The server was provisioned in us-east-1."
(Who provisioned it doesn't matter for this context.)
"The log file is rotated every 24 hours."
(The rotation mechanism is a background detail.)
When you want to emphasize the object over the actor:
"The database was corrupted during the power outage."
(The database corruption is the important part, not the
power outage's agency.)
In descriptions of system behavior where the system is the implicit actor:
"Requests are load-balanced across three instances."
(This is standard technical description. Rewriting as
"The load balancer distributes requests..." adds no clarity.)
The rule is not "never use passive voice." The rule is "use passive voice intentionally, not by default." If you find yourself writing passive voice, ask: would this be clearer if I named the actor? If yes, rewrite it. If no, the passive is fine.
Short Sentences Reduce Cognitive Load
The human brain processes information in chunks. Long sentences force readers to hold multiple ideas in working memory while waiting for the sentence to resolve. Short sentences deliver one idea at a time.
A good target for technical writing: keep most sentences under 25 words. This is not a rigid rule. Some sentences naturally need more words. But if your average sentence length is above 25 words, your writing is harder to read than it needs to be.
Long sentence (43 words):
"When the service receives a request that exceeds the rate limit
configured in the gateway settings, which defaults to 1000
requests per minute but can be overridden on a per-client basis,
it returns a 429 status code with a Retry-After header."
Broken into short sentences (same information):
"The gateway enforces a rate limit of 1000 requests per minute
by default. This limit can be overridden per client. When a
request exceeds the limit, the service returns a 429 status
code with a Retry-After header."
The information is identical. The short version is easier to read, easier to scan, and easier to reference later. Each sentence makes one clear statement.
One Idea Per Sentence
This is the principle behind short sentences, stated differently. Each sentence should express exactly one idea. When you find a sentence expressing two ideas, split it.
Two ideas jammed together:
"The caching layer reduces database load significantly and it
was implemented last quarter as part of the performance
improvement initiative led by the infrastructure team."
One idea per sentence:
"The caching layer reduces database load significantly. The
infrastructure team implemented it last quarter as part of
their performance improvement initiative."
Compound sentences joined by "and" are the most common offender. Every time you write "and" in the middle of a sentence, ask: should this be two sentences? Often the answer is yes.
Overloaded:
"The service starts, reads the configuration from the YAML file,
validates the schema, connects to the database, runs the pending
migrations, and begins accepting traffic on port 8080."
One idea per sentence:
"On startup, the service reads and validates its YAML
configuration file. It then connects to the database and runs
any pending migrations. Once migrations complete, the service
begins accepting traffic on port 8080."
The second version groups related actions into logical steps. Each sentence represents one phase of the startup process. A reader can follow the sequence without holding six actions in their head simultaneously.
Practical Techniques for Shorter Sentences
Cut throat-clearing phrases. These add words without adding meaning:
Remove Replace with
"It should be noted that..." (just state the thing)
"In order to..." "To..."
"Due to the fact that..." "Because..."
"At the present time..." "Now..." or "Currently..."
"In the event that..." "If..."
"For the purpose of..." "To..." or "For..."
"It is important to note..." (just state the thing)
"As a matter of fact..." (delete entirely)
Break at conjunctions. When you see "and," "but," "which," "while," or "although" in the middle of a long sentence, consider splitting there.
Before: "The queue processes messages in order, but if a message
fails three times, it moves to the dead letter queue, which is
monitored by the ops team, who will investigate and either replay
the message or mark it as permanently failed."
After: "The queue processes messages in order. If a message fails
three times, it moves to the dead letter queue. The ops team
monitors this queue. They investigate each failed message and
either replay it or mark it as permanently failed."
Remove relative clauses when possible. "Which" and "that" clauses often signal a sentence trying to do too much.
Before: "The API, which was originally designed for internal use
only but has since been adopted by three external partners who
require different authentication mechanisms, needs a redesign."
After: "The API was originally designed for internal use. Three
external partners now use it, each requiring different
authentication. The API needs a redesign."
Delete hedge words in technical writing. Words like "somewhat," "relatively," "fairly," and "quite" weaken your statements without adding precision. If you need to qualify, use specific qualifications.
Hedged: "The performance is somewhat degraded under relatively
high load conditions."
Specific: "Latency increases from 50ms to 300ms at 10,000
requests per second."
Rhythm & Variation
Short sentences should be the default, not the only tool. A document written entirely in five-word sentences reads like a children's book. Vary your sentence length to create rhythm.
The pattern that works: short, short, medium. Or: short, medium, short. Use a longer sentence when you need to connect two closely related ideas. Use a short sentence for emphasis.
"The deploy failed. The staging tests had passed. Every metric
looked normal. But we had not tested the interaction between the
new caching layer and the legacy authentication service. That
interaction caused a cascading failure across all three
availability zones. Total downtime: 47 minutes."
The short sentences create pace. The longer sentence in the middle provides the necessary detail. The final short sentence delivers the punch. This is not literary flourish — it is functional. The variation keeps the reader engaged and emphasizes the most important points.
Applying This to Different Document Types
Code review comments: Keep them to one or two sentences. State the issue, suggest the fix.
Wordy: "I noticed that this function, which is called on every
API request, is performing a database query that could be cached,
and given that we're already using Redis in this service, it
would probably be a good idea to cache the result."
Direct: "This function queries the database on every API request.
Cache the result in Redis — we already use it in this service."
Commit messages: First line under 72 characters. Active voice. State what the commit does, not what you did.
Passive and vague: "Some changes were made to fix the issue
that was reported."
Active and specific: "Fix null pointer in payment validation
when currency field is empty."
Design docs: Use short sentences for your recommendations and conclusions. Save longer sentences for nuanced trade-off discussions where you need to connect related ideas.
Incident reports: Active voice is especially critical here. Every event in the timeline should name its actor: the system, the engineer, the automated process.
"14:03 — Monitoring detects elevated error rate.
14:05 — PagerDuty alerts the on-call engineer.
14:08 — The on-call engineer begins investigation.
14:15 — The engineer identifies the failing database query.
14:22 — The engineer deploys a config change to disable the
new reporting feature.
14:25 — Error rate returns to baseline."
Every line names who or what took the action. The timeline is unambiguous.
Measuring Your Writing
You do not need a readability formula to check your writing. Two simple tests work:
The read-aloud test. Read your writing out loud. If you run out of breath mid-sentence, the sentence is too long. If you stumble over a phrase, the phrasing is awkward. If you lose track of the sentence's point before reaching the period, your reader will too.
The actor test. For each sentence, ask: who or what is doing the action? If you cannot answer immediately, the sentence is probably in passive voice and could be clearer.
Common Pitfalls
Over-correcting into choppy prose. Short sentences are good. But turning every sentence into a sentence fragment is not. You still need complete thoughts. The goal is clarity, not brevity for its own sake.
Using active voice when passive is genuinely better. "The server was decommissioned" is fine when the focus is on the server, not on who decommissioned it. Do not contort sentences into awkward active constructions just to follow the rule.
Confusing "short" with "simple." Short sentences can express complex ideas. "The system uses eventual consistency, so reads may return stale data for up to 5 seconds after a write." That is 19 words expressing a nuanced technical concept. Short does not mean dumbed down.
Ignoring sentence length in lists and tables. The principles apply everywhere, including list items, table cells, and figure captions. A 40-word bullet point defeats the purpose of using a list.
Not revising. First drafts are always longer and more convoluted than they need to be. The editing pass is where you split long sentences, switch passive to active, and cut unnecessary words. Build revision into your writing process — it is where clarity happens.
Key Takeaways
- Active voice names the actor and assigns responsibility. Use it by default. Switch to passive only when the actor is genuinely irrelevant or unknown.
- Keep most sentences under 25 words. This is not a rigid rule but a useful target that forces clarity.
- One idea per sentence. When a sentence expresses two ideas, split it into two sentences.
- Cut throat-clearing phrases, hedge words, and unnecessary conjunctions. They add words without adding meaning.
- Vary sentence length for rhythm. Short sentences for emphasis, medium sentences for connecting related ideas.
- Use the read-aloud test and the actor test to check your writing. If you stumble reading it aloud or cannot identify the actor, revise.