Define unfamiliar terms and abbreviations (EK00009)
Defining an abbreviation on first use lets first-time readers follow your documentation without guessing. Learn why, with examples and fixes.
Spelling out the full term the first time you use an abbreviation lets readers who don’t recognize it follow along. EkLine flags an abbreviation used before you define it (rule EK00009) so you can introduce the term on first use.
Why define abbreviations in documentation?
Section titled “Why define abbreviations in documentation?”Documentation reaches readers with a range of backgrounds, and an undefined abbreviation forces anyone who doesn’t know it to guess or search elsewhere. Defining the term once, on first use, keeps the page self-contained and accessible. After that first definition, the abbreviation alone is clear for the rest of the document.
What EkLine flags
Section titled “What EkLine flags”EK00009 matches an abbreviation that is used without being defined on first use. Common, widely understood abbreviations are exempt.
- ❌ Incorrect: Configure the SSO settings.
- ✅ Correct: Configure the single sign-on (SSO) settings.
- ❌ Incorrect: Enable RBAC for each project.
- ✅ Correct: Enable role-based access control (RBAC) for each project.
How to fix
Section titled “How to fix”Spell out the full term on first use and put the abbreviation in parentheses after it. Use the abbreviation on its own for every mention that follows.
When should you spell out an abbreviation?
Section titled “When should you spell out an abbreviation?”Spell out the full term on first use and put the abbreviation in parentheses after it. Use the abbreviation on its own for every mention that follows.
Which abbreviations don’t need a definition?
Section titled “Which abbreviations don’t need a definition?”Widely recognized abbreviations that are already common for your audience don’t need a definition. Keep those and ignore the rule for that line.
Rule details
Section titled “Rule details”| Property | Value |
|---|---|
| Rule ID | EK00009 |
| Category | Consistency |
| Default severity | Warning |
| Enabled by default | No |
Ignore this rule
Section titled “Ignore this rule”To keep an undefined abbreviation on one line, add an inline comment:
<!-- ekline-ignore-next-line EK00009 -- defined in the glossary -->Configure the SSO settings.To disable the rule across your project, add it to the ignore list in your configuration file.