# Prefer active voice over passive voice (EK00031)

import { Aside, Badge } from '@astrojs/starlight/components';

Active voice names who or what performs an action, which makes documentation direct and easy to follow. EkLine flags passive-voice sentences (rule EK00031) so you can rewrite them in active voice.

## Why use active voice in documentation?

Passive voice hides the actor. In documentation, the actor is usually the reader or the system, and readers need to know which. "The file is saved" leaves open whether the reader saves it or the software does. "Select **Save** to save the file" removes the doubt. Active voice is also shorter, so procedures read faster and translate more cleanly.

## What EkLine flags

EK00031 detects the pattern of a form of "to be" followed by a past participle, which signals passive voice.

- ❌ **Incorrect:** The configuration is validated by the server.
- ✅ **Correct:** The server validates the configuration.
- ❌ **Incorrect:** A confirmation email will be sent to you.
- ✅ **Correct:** EkLine sends you a confirmation email.

## How to fix

Identify who performs the action and make that the subject of the sentence:

1. Find the actor — the person or thing doing the action.
2. Put the actor at the start of the sentence.
3. Follow it with an active verb.

<Aside type="note">
Passive voice is sometimes the right choice — for example, when the actor is unknown or irrelevant, or when legal text requires it. In those cases, keep the sentence and ignore the rule for that line.
</Aside>

## FAQ

### How do you fix passive voice?

Find who performs the action and make that the subject of the sentence, then use an active verb. For example, "The file is saved by the app" becomes "The app saves the file."

### Should you ever use passive voice in documentation?

Yes. Passive voice works when the actor is unknown or irrelevant, or when legal wording requires it. Everywhere else, active voice is clearer.

## Rule details

| Property | Value |
|----------|-------|
| Rule ID | `EK00031` |
| Category | Tone and voice |
| Default severity | <Badge text="Warning" variant="caution" /> |
| Enabled by default | Yes |

## Ignore this rule

To keep a passive sentence on one line, add an inline comment with a reason:

```markdown
<!-- ekline-ignore-next-line EK00031 -- passive voice required by legal -->
The agreement must be signed before activation.
```

To disable the rule across your project, add it to the `ignore` list in your [configuration file](/reviewer/configuration/ignoring-rules/#ignore).

## Related rules

- [EK00005](/reviewer/rules/ek00005/) — Prefer present tense over future tense
- [EK00057](/reviewer/rules/ek00057/) — Write direct action statements
- [EK00047](/reviewer/rules/ek00047/) — Limit first-person pronouns