datadog·Feb 14, 2024Original article

How we use Vale to improve our documentation editing process | Datadog (opens in new tab)

To manage a high volume of technical content across dozens of products, Datadog’s documentation team has automated its editorial process using the open-source linting tool Vale. By integrating these checks directly into their CI/CD pipeline via GitHub Actions, the team ensures prose consistency and clarity while significantly reducing the manual burden on technical writers. This "shift-left" approach empowers both internal and external contributors to identify and fix style issues independently before a formal human review begins. ### Scaling Documentation Workflows * The Datadog documentation team operates at a 200:1 developer-to-writer ratio, managing over 1,400 contributors and 35 distinct products. * In 2023 alone, the team merged over 20,000 pull requests covering 650 integrations, 400 security rules, and 65 API endpoints. * On-call writers review an average of 40 pull requests per day, necessitating automation to handle triaging and style enforcement efficiently. ### Automated Prose Review with Vale * Vale is implemented as a command-line tool and a GitHub Action that scans Markdown and HTML files for style violations. * When a contributor opens a pull request, the linter provides automated comments in the "Files Changed" tab, flagging long sentences, wordy phrasing, or legacy formatting habits. * This automation reduces the "mental toll" on writers by filtering out repetitive errors before they reach the human review stage. ### Codifying Style Guides into Rules * The team transitioned from static editorial guidelines stored in Confluence and wikis to a codified repository called `datadog-vale`. * Style rules are defined using Vale’s YAML specification, allowing the team to update global standards in a single location that is immediately active in the CI pipeline. * Custom regular expressions are used to exclude specific content from validation, such as Hugo shortcodes or technical snippets that do not follow standard prose rules. ### Implementation of Specific Linting Rules * **Jargon and Filler Words:** A `words.yml` file flags "cruft" such as "easily" or "simply" to maintain a professional, objective tone. * **Oxford Comma Enforcement:** The `oxfordcomma.yml` rule uses regex to identify lists missing a serial comma and provides a suggestion to the author. * **Latin Abbreviations:** The `abbreviations.yml` rule identifies terms like "e.g." or "i.e." and suggests plain English alternatives like "for example" or "that is." * **Timelessness:** Rules flag words like "currently" or "now" to ensure documentation remains relevant without frequent updates. By open-sourcing their Vale configurations, Datadog provides a framework for other organizations to automate their style guides and foster a more efficient, collaborative documentation culture. Teams looking to improve prose quality should consider adopting a similar "docs-as-code" approach to shift editorial effort toward the beginning of the contribution lifecycle.

ValeDatadogCI/CDGitHub Actions+4

datadog·Feb 14, 2024·3 min readCurated summary

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.

Read original(opens in new tab)

ValeDatadogCI/CDGitHub Actions+4