Guidelines for using Active Voice in writing
Technical writing aims to simplify complex ideas, not to obscure them with unnecessarily convoluted language. However, passive voice often dominates technical documentation, leading to sentences that obscure who is responsible for actions and forcing readers to untangle meaning. Take this example: "The data is processed by the system, then results are generated and stored in the database." Who processes the data? What generates the results? Passive constructions conceal the actors and complicate comprehension.
Using active voice produces clear, actionable content, helping readers understand precisely what happens and who makes it happen. This first article in the Grammar for Technical Writers series explains how to spot passive voice, transform it into active constructions, and employ AI tools to streamline the editing process for existing documentation.
The Active Voice Formula
Google's Technical Writing Guide offers a straightforward formula for active voice: Actor + Verb + Target. This structure ensures direct, unambiguous sentences where the actor performs an action on a target.
Passive voice: "Code is interpreted by Python"
Active voice: "Python interprets code"
The active version clearly identifies the actor and reduces wordiness. According to research from the Plain Language Action and Information Network, readers process active voice sentences 23% faster than passive ones. In technical writing such as API documentation, error messages, and user guides this improvement in clarity and speed significantly enhances user comprehension and efficiency.
Active voice proves particularly valuable because it requires naming the actor in every sentence. For instance, writing "The database connection failed" leaves the cause ambiguous. Revising it to "The application couldn't connect to the database" immediately clarifies the issue.
Common Passive Voice Traps in Technical Writing
Technical writers frequently rely on passive voice structures that obscure critical information. Below are some common pitfalls and their active voice alternatives:
System Processes
Passive: "The data is processed by the system"
Active: "The system processes data"
Error Handling
Passive: "Errors are handled by the exception handler"
Active: "The exception handler catches errors"
Network Communication
Passive: "The request is sent to the server"
Active: "The client sends the request to the server"
Code Execution
Passive: "The function is called when the button is clicked"
Active: "Clicking the button calls the function"
Omitting the actor entirely represents the most problematic passive construction. For example, sentences like "The database was updated" or "The configuration file was modified" leave readers guessing who performed the action. Active voice alternatives make this clear: "The migration script updated the database" or "The installation process modified the configuration file."
Database documentation is particularly prone to this issue. Instead of writing, "Records are inserted into the users table," specify the actor: "The registration endpoint inserts records into the users table." This precision helps developers trace data flow and troubleshoot issues more effectively.
When Passive Voice Is Acceptable
Although rare, there are specific cases where passive voice is appropriate in technical writing:
Unknown Actor: When the actor is genuinely unknown, passive voice can clarify the situation. For example, "The server was compromised last night" works when an investigation is ongoing.
Target Emphasis: If the target of the action is more important than the actor, passive voice may be justified. "The critical bug was fixed in version 2.1" focuses attention on the resolution rather than the developer responsible.
Scientific Objectivity: In academic or research contexts, passive voice can help maintain objectivity. "The algorithm was tested on 10,000 samples" removes the researcher from the sentence. However, active voice, when possible, is still more engaging: "We tested the algorithm on 10,000 samples."
The guiding principle is to use passive voice only when it serves a deliberate purpose, not as the default.
Using AI Tools to Transition to Active Voice
Modern AI tools, such as Claude Code, can systematically identify and convert passive voice instances across entire documents. This saves hours of manual editing while ensuring consistency.
A Practical Workflow
Upload the document to Claude Code.
Run an analysis: Request identification of all passive voice constructions.
Convert systematically: Ask the tool to revise these into active voice while preserving technical accuracy.
Review and refine: Verify that the AI has maintained intended meaning and precision.
Before AI Cleanup:
"The API endpoint was called by the frontend application, and data was retrieved from the database. The response was then formatted and returned to the client."
After AI Cleanup:
"The frontend application calls the API endpoint and retrieves data from the database. The endpoint formats the response and returns it to the client."
This transformation clarifies the sequence of actions and highlights each actor. AI tools excel at catching overlooked passive constructions, particularly in lengthy documents where repetition makes them less noticeable.
Collaborating with AI tools leads to better results than one-off rewrites. By refining inputs over time, the AI adapts to your style preferences, ensuring consistency across documentation. This approach is especially useful for teams managing large documentation sets.
Start Writing Actively Today
Active voice enhances technical communication by making actions and actors explicit. It saves readers time by eliminating needless decoding, allowing them to focus on your content's meaning.
Begin with small changes, such as revising pull request descriptions. Instead of writing, "Changes were made to improve performance," write, "This commit improves performance by caching database queries." The clarity will be instantly apparent to your team.
Finally, use AI tools to conduct systematic audits of your existing documentation. The effort quickly pays off as your audience navigates and understands your technical content without unnecessary friction.