Prefer active voice over passive voice (EK00031)
Active voice makes documentation clearer by naming who does what. Learn why to use it instead of passive voice, with examples and fixes.
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?
Section titled “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
Section titled “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
Section titled “How to fix”Identify who performs the action and make that the subject of the sentence:
- Find the actor — the person or thing doing the action.
- Put the actor at the start of the sentence.
- Follow it with an active verb.
How do you fix passive voice?
Section titled “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?
Section titled “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
Section titled “Rule details”| Property | Value |
|---|---|
| Rule ID | EK00031 |
| Category | Tone and voice |
| Default severity | Warning |
| Enabled by default | Yes |
Ignore this rule
Section titled “Ignore this rule”To keep a passive sentence on one line, add an inline comment with a reason:
<!-- 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.