Write direct action statements (EK00057)
Direct action statements make documentation shorter and clearer. Learn how to replace phrases like allows you to with the action itself.
A direct action statement tells the reader what to do or what a feature does, without a filler wrapper, which keeps documentation short and clear. EkLine flags indirect phrasing such as allows you to and openers like This document describes (rule EK00057) so you can rewrite them.
Why write direct action statements in documentation?
Section titled “Why write direct action statements in documentation?”Phrases like “allows you to” and “this document describes” add a layer between the reader and the point. “This feature allows you to edit files” buries the action; “Edit files” states it. Cutting the wrapper makes instructions shorter and puts the verb where readers look for it. Direct openings also help readers judge relevance in the first line.
What EkLine flags
Section titled “What EkLine flags”EK00057 detects enabling phrases such as allows you to, enables you to, and lets you, along with document-focused openers such as This document describes, This page explains, and The purpose of this document is.
- ❌ Incorrect: This feature allows you to edit files.
- ✅ Correct: Edit files.
- ❌ Incorrect: This page describes the API.
- ✅ Correct: The API returns JSON.
How to fix
Section titled “How to fix”Drop the wrapper and lead with the action or the fact. Replace “This feature allows you to edit files” with “Edit files”, and start a page with its content rather than “This page describes”.
How do you rewrite “allows you to”?
Section titled “How do you rewrite “allows you to”?”Drop the wrapper and lead with the action. “This feature allows you to edit files” becomes “Edit files.”
What’s wrong with an opener like “This page describes”?
Section titled “What’s wrong with an opener like “This page describes”?”It delays the point. Starting with the content itself helps readers judge relevance in the first line.
Rule details
Section titled “Rule details”| Property | Value |
|---|---|
| Rule ID | EK00057 |
| Category | Tone and voice |
| Default severity | Warning |
| Enabled by default | No |
Ignore this rule
Section titled “Ignore this rule”To keep an indirect phrase on one line, add an inline comment with a reason:
<!-- ekline-ignore-next-line EK00057 -- phrasing required for legal clarity -->This document describes the terms of the agreement.To disable the rule across your project, add it to the ignore list in your configuration file.