Active vs Passive Voice — Choosing the Right Verb Voice for Technical Documentation

In this tutorial, you will learn about Active vs Passive Voice. We cover key concepts, practical examples, and best practices to help you master this topic.

Active voice makes sentences clearer and shorter by having the subject perform the action. Passive voice places the object of the action first and hides who performs it. Choosing the right voice is one of the most impactful style decisions in technical writing.

In this lesson, you will learn when to use active voice and when passive voice is appropriate for technical documentation.

What You'll Learn

You will understand the difference between active and passive voice, know when each is appropriate, and write predominantly in active voice for clearer documentation.

Why It Matters

Active voice reduces sentence length by 20 to 30 percent and makes writing easier to understand. Readers Process active sentences faster than passive ones.

Real-World Use

DodaTech enforced active voice in all documentation using Vale rules. Passive voice instances dropped by 80 percent. User testing showed a 15 percent improvement in task completion time.

flowchart LR
  A[Subject] --> B[Action]
  B --> C[Object]
  C --> D[Active: Subject acts]
  D --> E[Clear and Direct]
  A:::current
  classDef current fill:#f90,color:#fff,stroke:#333,stroke-width:2px

Active Voice Examples

In active voice, the subject performs the action. The API returns a list of users is active. The subject API performs the action returns.

Use active voice for instructions addressed to the reader. Click Submit is active. The Submit button should be clicked is passive.

Use active voice when the subject is known and important. The developer configures the API tells us who does what.

# Active Voice (Preferred)
The algorithm compresses the file.
The server validates the request.
You must reset your password.
The API returns 404 if the page does not exist.

# Passive Voice (Avoid unless needed)
The file is compressed by the algorithm.
The request is validated by the server.
The password must be reset by the user.
A 404 error is returned when the page is not found.

When Passive Voice Is Appropriate

Passive voice is useful when the actor is unknown or unimportant. The package was released in 2024 does not need to say who released it.

Use passive voice when the recipient of the action is more important than the actor. The file was compressed successfully focuses on the file, not who compressed it.

Use passive voice to avoid blaming the reader. The setting was configured incorrectly is gentler than You configured the setting incorrectly.

# Good Uses of Passive Voice

# Actor unknown
The library was first released in 2024.

# Recipient more important
Your request has been received.

# Avoiding blame
The configuration file was not found. (vs You placed the file wrong)

Common Mistakes

1. Defaulting to Passive

Writing everything in passive voice because it sounds formal. Active voice is more direct and professional.

2. Overcorrecting to Active

Using active voice when passive is more appropriate. Learn both and choose based on context.

3. Passive Hides Responsibility

Errors were made without saying who made them. Use active voice for accountability.

4. Mixed Voice in Sentences

Starting active and switching to passive. The server validates the request and a response is returned should be The server validates the request and returns a response.

5. Passive in Instructions

The file should be saved before closing sounds like a suggestion, not an instruction. Save the file before closing.

6. Unnecessary Passive Modals

The file can be compressed becomes The algorithm can compress the file or better The algorithm compresses the file.

7. Ignoring the Agent

The form must be submitted is incomplete. Who must submit it? You must submit the form.

Practice Questions

1. What is active voice?

The subject performs the action. The API returns a list is active. The subject API performs the action returns.

2. When should you use passive voice?

When the actor is unknown, unimportant, or when you want to focus on the recipient of the action rather than the actor.

3. Why does active voice improve documentation?

It is shorter, clearer, and tells the reader exactly who does what. Readers understand active sentences faster.

4. How can you check for passive voice automatically?

Use Vale or similar linters that flag passive voice constructions like is returned, are used, was compressed.

5. Challenge: Take a page of documentation that has at least 10 passive voice constructions. Rewrite each one in active voice. Note any cases where passive voice was the better choice and explain why.

FAQ

Mini Project

Audit a documentation page for passive voice. Identify every passive construction. For each, decide whether active voice would be better. Rewrite the page with appropriate voice choices. Use Vale to verify your changes.

What's Next

Next: Sentence Structure