Word Usage Verification Rule

This rule helps ensure consistent and appropriate word usage by flagging potentially problematic or ambiguous terms that need to be verified against Microsoft's A-Z word list style guide. It's important because certain common words can be misused, carry unintended connotations, or may not be inclusive enough for technical documentation.

The rule suggests reviewing words that:

  • May have specific technical meanings (e.g., "abort," "alert")
  • Could be gender-biased (e.g., "he," "she")
  • Might be ambiguous or overused (e.g., "allows," "ensure," "assure")
  • Could indicate incomplete content (e.g., "beta," "sample")

Examples:

The rule will flag:

  • ✗ "The user should ensure that all settings are correct"
  • ✗ "He can access the database"
  • ✗ "This feature allows users to export data"
  • ✗ "The beta version is now available"

When these words are flagged, authors should consult the Microsoft Style Guide's A-Z word list to verify proper usage and consider alternative phrasing if needed.

Note that this is a suggestion-level rule, meaning it won't block content but rather encourages authors to review their word choices thoughtfully.

Rule Source

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

Rule Definition

extends: existence
message: "Verify your use of '%s' with the A-Z word list."
link: 'https://docs.microsoft.com/en-us/style-guide/a-z-word-list-term-collections/a/abort-abortion'
level: suggestion
ignorecase: true
tokens:
  - above
  - accessible
  - actionable
  - against
  - alarm
  - alert
  - alias
  - allows?
  - assure
  - author
  - avg
  - ensure
  - he
  - insure
  - she
  - sample
  - beta