Terminology and Brand Name Consistency Rule

This rule enforces consistent capitalization and styling of technical terms, brand names, and common phrases in technical documentation. Maintaining consistent terminology is crucial for professionalism, clarity, and alignment with official brand guidelines. It helps ensure that product names, technologies, and technical terms are written correctly throughout the documentation, enhancing readability and credibility.

Examples:

  • ❌ "I'm using github for version control" → ✅ "I'm using GitHub for version control"
  • ❌ "The typescript code needs review" → ✅ "The TypeScript code needs review"
  • ❌ "We built this with javascript and css" → ✅ "We built this with JavaScript and CSS"
  • ❌ "Open it in VSCode" → ✅ "Open it in VS Code"
  • ❌ "You can find the demo in codesandbox" → ✅ "You can find the demo in CodeSandbox"
  • ❌ "This is a client side solution" → ✅ "This is a client-side solution"
  • ❌ "A common use-case for this" → ✅ "A common use case for this"

The rule is case-insensitive and handles various common misspellings and incorrect formatting of technical terms, ensuring they match official styling guidelines (like npm being lowercase, JavaScript having a capital 'J' and 'S', etc.).

Rule Source

This rule comes from: https://github.com/mui/material-ui

Rule Definition

# Enforce a single way to write specific terms or phrases.
extends: substitution
message: Use '%s' instead of '%s'
level: error
ignorecase: true
# swap maps tokens in form of bad: good
# for more information: https://vale.sh/docs/topics/styles/#substitution
swap:
  ' api': API
  typescript: TypeScript
  ' ts': TypeScript
  javascript: JavaScript
  ' js': JavaScript
  ' css ': CSS
  ' html ': HTML
  NPM: npm # https://css-tricks.com/start-sentence-npm/
  Github: GitHub
  StackOverflow: Stack Overflow
  Stack Overflow: Stack Overflow
  CSS modules: CSS Modules
  Tailwind CSS: Tailwind CSS
  Heat map: Heatmap
  Tree map: Treemap
  Sparkline Chart: Sparkline
  Gauge Chart: Gauge
  Treemap Chart: Treemap
  sub-component: subcomponent
  sub-components: subcomponents
  use-case: use case
  usecase: use case
  client side: client-side
  server side: server-side
  Material 3: Material Design 3
  VSCode: VS Code
  VS Code: VS Code
  'Codesandbox ': CodeSandbox
  code sandbox: CodeSandbox
  Stackblitz: StackBlitz
  Webpack: webpack # https://twitter.com/wSokra/status/855800490713649152