Avoid idioms and colloquialisms (EK00043)
Plain, literal phrasing reads clearly for every reader, whatever their first language. Replace idioms and colloquialisms so documentation travels well.
Plain, literal phrasing reads clearly for every reader, regardless of first language. EkLine flags idioms and colloquialisms that may confuse a global audience and suggests a plain equivalent (rule EK00043).
Why avoid idioms in documentation?
Section titled “Why avoid idioms in documentation?”Idioms like keep in mind carry meaning that isn’t obvious from the words themselves, which trips up non-native readers and translation tools. A plain equivalent conveys the same idea without the cultural context. Clear phrasing widens your audience and reduces support questions.
What EkLine flags
Section titled “What EkLine flags”EK00043 flags an idiom or colloquialism that has a plain equivalent.
- ❌ Incorrect: Keep in mind the rate limit.
- ✅ Correct: Consider the rate limit.
- ❌ Incorrect: Run the CLI to figure out the cause.
- ✅ Correct: Run the CLI to determine the cause.
- ❌ Incorrect: In light of the change, update your config.
- ✅ Correct: Because of the change, update your config.
How to fix
Section titled “How to fix”Replace the idiom with the plain equivalent EkLine suggests.
Why are idioms a problem in documentation?
Section titled “Why are idioms a problem in documentation?”Idioms carry meaning that isn’t obvious from the words themselves, which trips up non-native readers and translation tools. A plain equivalent conveys the same idea without the cultural context.
What can you use instead of an idiom?
Section titled “What can you use instead of an idiom?”Use the literal equivalent — “keep in mind” becomes “consider”, and “figure out” becomes “determine”. The plain phrase widens your audience and reduces support questions.
Rule details
Section titled “Rule details”| Property | Value |
|---|---|
| Rule ID | EK00043 |
| Category | Sentences and phrases |
| Default severity | Suggestion |
| Enabled by default | Yes |
Ignore this rule
Section titled “Ignore this rule”To keep a flagged idiom on one line, add an inline comment with a reason:
<!-- ekline-ignore-next-line EK00043 -- idiom in a customer quote -->"This tool helped us figure out the root cause fast."To disable the rule across your project, add it to the ignore list in your configuration file.