Linting Tools for Documentation — Complete Guide

In this tutorial, you will learn about Linting Tools for Documentation. We cover key concepts, practical examples, and best practices to help you master this topic.

Linting tools automate style and quality checks for documentation. Compare Vale, alex, and proselint for prose linting, with configuration examples for enforcing style guides and catching terminology issues.

What You'll Learn

You will learn how to configure prose linters for documentation, how they differ, and how to integrate them into your docs-as-code pipeline.

Why It Matters

Manual proofreading is slow and inconsistent. Prose linters catch style violations, terminology errors, and readability issues automatically, enforcing consistency across all documentation.

Real-World Use

DodaTech uses Vale with the Google Developer Documentation Style Guide. It runs on every PR, catching informal language, passive voice, and terminology violations.

flowchart LR
  A[Markdown File] --> B[Prose Linter]
  B --> C[Style Guide Rules]
  B --> D[Terminology Rules]
  B --> E[Readability Check]
  C --> F{Pass or Fail?}
  D --> F
  E --> F
  F --> G[CI Result]
  A:::current
  classDef current fill:#f90,color:#fff,stroke:#333,stroke-width:2px

Tool Comparison

Vale Configuration

# .vale.ini
StylesPath = .vale/styles

[formats]
markdown = md

[*]
BasedOnStyles = Vale, Google

[*.md]
Vale.Spelling = YES
Google.WordList = YES
Google.Gender = YES

# Install Vale and download styles
brew install vale
mkdir -p .vale/styles
git clone https://github.com/errata-ai/google.git .vale/styles/Google

Running Vale

vale content/api/authentication.md

Expected output:

 content/api/authentication.md
 1:1  warning  'login' is informal. Use 'sign in'.  Google.WordList
 45:12  warning  Use 'can' instead of 'may'  Google.CanMay
 89:5  error  'Utilize' is unnecessarily complex. Use 'use'.

alex Configuration

{
  "allow": [],
  "noBinary": true,
  "profanitySureness": 1
}

# Run alex
alex content/ --why

# Expected output
content/api/authentication.md
  23:15-23:20  warning  `whitelist` may be insensitive  retext-equality

proselint Configuration

{
  "checks": {
    "weasel_words": true,
    "passive_voice": true,
    "lexical_illusions": true,
    "redundancy": true,
    "style": true
  }
}

# Run proselint
proselint content/api/authentication.md

Common Mistakes

1. Running Linters Only in CI

Writers need immediate feedback. Run linters in the editor and as pre-commit hooks so issues are caught before CI.

2. Enforcing Too Many Rules

Starting with 100+ rules overwhelms writers. Begin with 10-20 essential rules and add more as the team adapts.

3. Not Customizing Rules for Your Project

Generic rules catch generic issues. Customize rules for your product terminology, brand voice, and audience.

4. Ignoring False Positives

Linters produce false positives. Have a Process to review and adjust rules instead of ignoring them.

5. Not Documenting Rules for Writers

Writers need to know what rules exist and why. Add a style guide section explaining the linting rules.

Practice Questions

1. What is the difference between Vale and alex?

Vale is a general-purpose prose linter with customizable style rules. alex focuses on detecting insensitive language and terminology issues.

2. Why should linters run in the editor, not just in CI?

Editor integration gives writers immediate feedback, fixing issues before committing.

3. How do you configure Vale to use a specific style guide?

Create a .vale.ini that specifies which style packages to use (Google, Microsoft, write-good).

4. What is the risk of running too many linting rules?

Too many rules overwhelm writers and lead to alert fatigue. Writers start ignoring or bypassing linter warnings.

5. Challenge: Configure Vale with the Google style guide and add three custom terminology rules for your product. Run it on a sample documentation page and fix all violations.

FAQ

Mini Project

Set up a Vale configuration using the Google Developer Documentation Style Guide. Create three custom terminology rules for your product. Configure a GitHub Actions workflow that runs Vale on every PR. Fix all violations on a sample page.

What's Next

After linting, explore Link Checking tools like HTMLProofer and lychee. Then learn about Image Editing for documentation.