Avoid potentially condescending language (EK00003)
Removing words like obviously or simply keeps your documentation clear and welcoming to readers who are stuck. Learn why, with examples.
Words that assume a task is easy or self-evident, such as simply or obviously, add no information and can make a reader who is stuck feel talked down to, so removing them keeps your documentation clear and welcoming. EkLine flags these words (rule EK00003) so you can cut them and keep the instruction intact.
Why avoid condescending language in documentation?
Section titled “Why avoid condescending language in documentation?”Words like “simply” and “obviously” describe your own sense of difficulty, not the reader’s. When a step turns out to be hard, that framing signals the reader is at fault, which erodes trust in the page. Cutting these words also tightens your prose, because each one you remove leaves the instruction intact.
What EkLine flags
Section titled “What EkLine flags”EK00003 matches words that can sound condescending, including “obviously”, “basically”, “simply”, “easily”, “of course”, “clearly”, and “everyone knows”.
- ❌ Incorrect: Simply run the command.
- ✅ Correct: Run the command.
- ❌ Incorrect: Obviously, you need an account.
- ✅ Correct: You need an account.
How to fix
Section titled “How to fix”Remove the flagged word. The sentence keeps its meaning, and the instruction reads as direct.
Why is “simply” discouraged in documentation?
Section titled “Why is “simply” discouraged in documentation?”Words like “simply” describe your own sense of difficulty, not the reader’s. When a step turns out to be hard, that framing signals the reader is at fault, which erodes trust in the page.
What should you write instead of “obviously” or “simply”?
Section titled “What should you write instead of “obviously” or “simply”?”Remove the word. The sentence keeps its meaning, and the instruction reads as direct.
Rule details
Section titled “Rule details”| Property | Value |
|---|---|
| Rule ID | EK00003 |
| Category | Inclusive language |
| Default severity | Error |
| Enabled by default | Yes |
Ignore this rule
Section titled “Ignore this rule”To keep a flagged word on one line, add an inline comment with a reason:
<!-- ekline-ignore-next-line EK00003 -- "clearly" describes a visible state -->The indicator turns green when the build clearly succeeds.To disable the rule across your project, add it to the ignore list in your configuration file.