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

Active and passive voice

Active voice keeps the actor and the action clear, so it’s the default. Passive voice isn’t banned — it’s a deliberate choice for sentences where the actor is unknown or irrelevant, or where the receiver of the action is the topic.

Default to active voice

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

Default to active voice, but choose passive voice when it serves the sentence better: when the actor is unknown, irrelevant, or generic; when the receiver of the action is the sentence’s topic; when active voice creates awkward complexity or false attribution; or when passive voice is the genre convention. Be intentional about the choice.

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 usually keeps the actor and action clear and the sentence direct. Passive voice is the better choice when the actor is unknown or irrelevant, the receiver is the sentence’s topic, or the genre expects it, so the rule defaults to active while leaving passive available when it serves the sentence.