Skip to content
Developer Experience Docs
The style guide is in beta: content and structure may change.

Active and passive voice

Active voice names the actor and is the default for developer documentation. Passive voice can be clearer when the actor doesn’t matter or the receiver of the action is the topic. Use this page when choosing the voice for a sentence or reviewing passive constructions.

Default to active voice

Section titled “Default to active voice”
passive-001 should GuidesAPI docsMarketingBlog

Default to active voice. Choose passive voice when the actor is unknown, irrelevant, or generic. Passive voice can also serve the sentence better when the receiver of the action is the topic, active voice creates awkward complexity or false attribution, or the genre convention calls for it. Choose the voice deliberately.

Examples

  • ✓ The client library validates the request before sending it.
  • ✗ The request is validated by the client library before it’s sent.
  • ✓ Inactive accounts are deactivated after 90 days.
  • ✗ The system deactivates inactive accounts after 90 days.

Rationale

Active voice keeps the actor and the action clear and the sentence direct. In the second example pair, the accounts are the topic and the system is a generic actor, so the passive sentence keeps the focus on the accounts. Active sentences also tend to translate more predictably because passive constructions differ across languages.