How we use Vale to improve our documentation editing process

Datadog’s Documentation team uses automated style linting to maintain clear, consistent prose across a large, fast-moving documentation repository. By integrating the open-source Vale linter into local authoring workflows and GitHub Actions, the team moves copy editing closer to the moment content is written. This reduces review effort, helps contributors fix issues themselves, and makes the team’s style guide executable rather than scattered across multiple documents.

Documentation at Scale

• The Documentation team grew from 7 to 14 writers while supporting roughly 200 developers per writer.
• The repository includes documentation for 35 products and more than 1,400 internal and external contributors.
• In 2023, the team merged more than 20,000 pull requests covering:
  • 30+ products
  • 65 API endpoints
  • 95 Marketplace integrations
  • 400 security compliance rules
  • 400 workflow actions
  • 650 integrations
• An on-call writer reviews more than 40 pull requests per day, making automated consistency checks especially valuable.

Why Manual Style Enforcement Falls Short

• Writers must catch issues such as:
  • Jargon and wordy phrasing
  • Malapropisms
  • Mismatched tenses
  • Gendered language
  • Typewriter-era formatting habits
  • Organization-specific preferences
• Contributors and AI writing tools may not know Datadog’s conventions, such as using serial commas, avoiding “via,” or eliminating time-sensitive words like “currently.”
• Previously, style guidance had to be maintained in Confluence, review documentation, contributing guides, and repository wiki pages.

Vale in Authoring and CI

• Datadog adopted Vale, an open-source command-line prose linter, through the datadog-vale project.
• A GitHub Action runs Vale against Markdown and HTML files in pull requests.
• The repository’s vale.ini file identifies:
  • Where style rules are stored
  • Which rules should run
  • Which content formats should be checked
• Automated comments appear in GitHub’s Files Changed view, allowing contributors to correct issues before a writer reviews the pull request.
• Vale has reduced editing time and the mental burden on writers while improving contributor self-service.

Turning the Style Guide into Rules

• Existing editorial guidelines were converted into YAML-based Vale rules.
• New rules can be added once and enforced everywhere, avoiding duplicated documentation.
• Regular expressions exclude content that should not be linted, such as Hugo shortcodes.
• Rules can identify both broad writing problems and precise organizational preferences.

Examples of Vale Rules

• A words.yml file can flag unnecessary jargon or “cruft” such as “easily” and “simply.”
• An oxfordcomma.yml rule detects sentences that omit the Oxford comma and provides a correction message and link to the relevant style guidance.
• An abbreviations.yml rule replaces Latin abbreviations with plain-English alternatives:
  • e.g. → “for example”
  • i.e. → “that is”
  • etc. → “and more”
• Vale rules can define severity levels such as suggestion or error, include explanatory messages, link to documentation, and optionally perform replacements.

Datadog’s approach demonstrates that documentation quality can be improved by treating prose standards like code standards: encode them as rules, run them continuously, and give authors immediate, actionable feedback. Teams with large contributor bases can use Vale and CI to make their style guide consistent, discoverable, and easier to maintain.