Undefined Acronym Check

This rule checks for undefined acronyms in text by ensuring that acronyms (sequences of 3-5 capital letters) are properly defined on their first use. The rule enforces a best practice in technical writing where acronyms should be spelled out on their first appearance, followed by the acronym in parentheses. This helps readers understand technical content better, especially when they might not be familiar with all industry-specific terminology.

The rule includes a comprehensive list of common technical acronyms (like HTML, CSS, API, etc.) that are considered well-known enough to not require definition.

Examples:

✗ Incorrect:

The SMTP server is not responding.

(Flagged because SMTP is used without first being defined)

✓ Correct:

The Simple Mail Transfer Protocol (SMTP) server is not responding.

✓ Also correct:

The HTML document needs to be updated.

(Not flagged because HTML is in the exceptions list)

The rule will flag any uppercase acronym of 3-5 letters that's not in the exceptions list and hasn't been properly defined with its full form first. This helps maintain documentation clarity and accessibility for readers of all technical levels.

Rule Source

This rule comes from: https://github.com/mesosphere/dcos-docs-site

Rule Definition

extends: conditional
message: "'%s' has no definition."
link: https://docs.microsoft.com/en-us/style-guide/acronyms
level: suggestion
ignorecase: false
# Ensures that the existence of 'first' implies the existence of 'second'.
first: '\b([A-Z]{3,5})\b'
second: '(?:\b[A-Z][a-z]+ )+\(([A-Z]{3,5})\)'
# ... with the exception of these:
exceptions:
  - API
  - ASP
  - CLI
  - CPU
  - CSS
  - CSV
  - DEBUG
  - DOM
  - DPI
  - FAQ
  - GCC
  - GDB
  - GET
  - GNU
  - GPU
  - GTK
  - GUI
  - HTML
  - HTTP
  - HTTPS
  - IDE
  - JAR
  - JSON
  - JSX
  - LESS
  - LLDB
  - MIT
  - NET
  - NOTE
  - NVDA
  - OIDC
  - OSS
  - PATH
  - PDF
  - PHP
  - POST
  - RAM
  - REPL
  - RSA
  - SCM
  - SCSS
  - SDK
  - SQL
  - SSH
  - SSL
  - SVG
  - TBD
  - TCP
  - TODO
  - URI
  - URL
  - USB
  - UTF
  - XML
  - XSS
  - YAML
  - ZIP