Prefer simple, concise words (EK00038)
Simple, concise words reach a wider audience and read faster without losing meaning. Learn why to choose plain synonyms in your documentation.
Simple words reach a wider audience and read faster than complex vocabulary, without losing meaning, so choose the plainer synonym. EkLine flags a complex word that has a simpler equivalent and suggests the plainer choice (rule EK00038).
Why prefer simple words in documentation?
Section titled “Why prefer simple words in documentation?”Complex vocabulary slows readers and raises the barrier for anyone reading in a second language. A word like accomplish rarely says more than do, yet it costs the reader more effort. Choosing the simpler synonym keeps your documentation clear and inclusive.
What EkLine flags
Section titled “What EkLine flags”EK00038 flags a complex word that has a shorter, simpler equivalent.
- ❌ Incorrect: This accelerates the build.
- ✅ Correct: This speeds up the build.
- ❌ Incorrect: You can accomplish this with one command.
- ✅ Correct: You can do this with one command.
- ❌ Incorrect: approximately 10 files
- ✅ Correct: about 10 files
How to fix
Section titled “How to fix”Replace the flagged word with the simpler synonym EkLine suggests. Keep the complex word only when it carries a precise technical meaning the simpler word loses.
Why do simple words improve documentation?
Section titled “Why do simple words improve documentation?”Simple words lower the barrier for readers, especially anyone reading in a second language, and they read faster. A word like “accomplish” rarely says more than “do”.
When should you keep a complex word?
Section titled “When should you keep a complex word?”Keep the complex word when it carries a precise technical meaning that the simpler synonym would lose. Everywhere else, the plainer choice is clearer.
Rule details
Section titled “Rule details”| Property | Value |
|---|---|
| Rule ID | EK00038 |
| Category | Sentences and phrases |
| Default severity | Suggestion |
| Enabled by default | No |
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 EK00038 -- precise technical term -->The scheduler accomplishes the rollout in three ordered phases.To disable the rule across your project, add it to the ignore list in your configuration file.