Consistency in Technical Terms and Common Expressions

This rule enforces consistent usage of technical terminology, abbreviations, and common expressions in technical documentation. It operates as a substitution rule that replaces less preferred terms with their standardized alternatives. Maintaining consistency in technical terminology is crucial for:

  • Reducing reader confusion
  • Maintaining professional documentation standards
  • Ensuring clarity across documentation
  • Following industry-standard conventions

The rule helps maintain consistency especially in areas like:

  • Technical terms and units
  • Digital storage units (KB, MB, GB, etc.)
  • Common technical concepts
  • Latin expressions
  • Device and software terminology

Examples:

  1. Storage Units:

    • gb → GB
    • mb → MB
    • kb → KB

  2. Technical Terms:

    • drive C: → drive C
    • virtual assistant → personal digital assistant
    • chatbot → chatbot(s)
    • anti-virus → antivirus

  3. Common Expressions:

    • 24/7 → every day
    • viz → namely
    • ergo → therefore

  4. Device Terms:

    • smart phone → phone
    • mobile phone → phone
    • internet bot → bot

The rule flags these terms with a warning message in the format "Prefer 'X' over 'Y'" and can automatically suggest the correct replacement.

Rule Source

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

Rule Definition

extends: substitution
message: "Prefer '%s' over '%s'."
level: warning
ignorecase: true
action:
  name: replace
swap:
  '(?:agent|virtual assistant|intelligent personal assistant)': personal digital assistant
  '(?:drive C:|drive C>|C: drive)': drive C
  '(?:internet bot|web robot)s?': bot(s)
  '(?:microsoft cloud|the cloud)': cloud
  '(?:mobile|smart) ?phone': phone
  '24/7': every day
  'audio(?:-| )book': audiobook
  'back(?:-| )light': backlight
  'chat ?bots?': chatbot(s)
  adaptor: adapter
  administrate: administer
  afterwards: afterward
  alphabetic: alphabetical
  alphanumerical: alphanumeric
  anti-aliasing: antialiasing
  anti-malware: antimalware
  anti-spyware: antispyware
  anti-virus: antivirus
  appendixes: appendices
  artificial intelligence: artificial intelligence
  assembler: assembly language
  bpp: bpp
  bps: bps
  caap: CaaP
  conversation-as-a-platform: conversation as a platform
  eb: EB
  gb: GB
  gbps: Gbps
  kb: KB
  keypress: keystroke
  mb: MB
  pb: PB
  tb: TB
  zb: ZB
  viz: namely
  ergo: therefore