How to Lint Your Documentation Before a PR Review

Documentation review has two distinct problems. The first is style and consistency: passive voice, the wrong word for "click," a product name that does not match the style guide. The second is content accuracy: did the subject matter expert agree with this description? Is the legal language correct? Does this match what the product actually does?

Tools should handle the first problem so that humans can focus on the second. When style issues reach your reviewers, two things go wrong. Reviewer attention splits between mechanical corrections and real content judgment. And review cycles multiply, because every round has mixed feedback types. Linting before the PR eliminates the first problem at the source.

Why Docs-as-Code Teams Need a Linting Step

Docs-as-code workflows treat documentation like software: write in Markdown or AsciiDoc, store in Git, review through pull requests. The process works well for version control and tooling. It has a gap on the quality side, because most CI pipelines do not enforce prose style the way they enforce code formatting.

The result is that style inconsistencies accumulate across documents. Different writers use different terminology. Some files follow the Microsoft style guide; others follow Google's. Passive voice appears in some sections but not others. None of this gets caught until a reviewer notices it, at which point the cycle includes a correction round that a tool should have handled automatically.

A linting step before the PR closes this gap. It gives writers a fast feedback loop before the content goes to review, and it protects reviewers from spending time on issues that are not within their area of judgment.

Vale: The Standard Prose Linter for Technical Docs

Vale is an open-source prose linter built for technical documentation. It works like a code linter: configure a set of rules, run Vale against your files, and get a list of violations with file and line references.

Vale is widely used in docs-as-code teams because of its rule package ecosystem. Microsoft, Google, Red Hat, GitLab, and others publish official Vale packages that encode their public style guides as machine-checkable rules. One tool, one configuration, consistent results across every file in your repository.

Vale supports Markdown, MDX, AsciiDoc, HTML, and plain text. It runs locally, in CI, or in the browser.

Browser-Based Linting: No Installation Required

The traditional Vale setup involves installing the CLI, writing a .vale.ini configuration file, and downloading style packages. For a CI pipeline this is the right approach. For a quick pre-PR check on a file you just edited, it is too much friction.

ProseLint Web solves this by running Vale as WebAssembly directly in your browser. No installation, no account, no configuration to maintain. Paste your content or upload a file, choose a style guide, and get linting results in seconds. Your document never leaves your device.

The tool includes the same rule packages that teams use in CI: Microsoft, Google, Red Hat, GitLab, and more. If your CI pipeline runs the Microsoft style guide, you can use the same package locally before your PR opens.

A Practical Pre-PR Linting Checklist

Before you open your pull request:

1. Open ProseLint Web and paste or upload the files you changed in this branch.
2. Select the style guide your team uses. If you are not sure, Microsoft is the most common default for technical writing teams.
3. Work through errors first. Errors are definite violations. Warnings are suggestions.
4. For intentional exceptions (a product name that triggers a rule, passive voice in an API reference), add a note to your PR description explaining each one.
5. Re-run the linter until the error count is zero or every remaining item is documented.
6. Commit the clean files to your branch, then open the PR.

This takes five to ten minutes for most changes. The investment pays back in shorter review cycles and less back-and-forth with reviewers.

Choosing the Right Style Guide

The right style guide depends on your audience and team:

• Microsoft Writing Style Guide: The most widely adopted choice for technical documentation teams. Conservative, thorough, and well understood across the industry. Use this as the default unless you have a specific reason not to.
• Google Developer Documentation Style Guide: A better fit for developer-facing content, API references, and tutorials aimed at engineers. Slightly more permissive on voice and tone.
• Red Hat Documentation Style Guide: Designed for open-source software and infrastructure documentation. Covers terminology specific to Linux, containers, and cloud infrastructure.
• Custom rules: ProseLint Web includes a visual rule builder for company-specific terminology. If your team has preferred product names, banned phrases, or required capitalization, encode them as custom rules and the linter enforces them automatically.

Consistency between local linting and CI configuration matters. If CI runs the Microsoft package and you lint locally with Google's, you will pass local checks but fail CI. Pick one and use it everywhere.

Adding Vale to CI for Automated Enforcement

Browser linting handles the individual pre-PR check. For teams who want enforcement on every PR regardless of whether the writer ran a local check, add Vale to CI:

# .github/workflows/vale.yml
name: Lint documentation

on: [pull_request]

jobs:
  vale:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: errata-ai/vale-action@v2
        with:
          files: docs
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

This creates two enforcement layers. ProseLint Web gives writers immediate feedback during writing. Vale in CI enforces consistency on every PR as a hard gate. Both layers use the same rule packages, so the results are predictable.

After Linting: The Stakeholder Review Step

Clean, linted content is ready for review. For internal technical review from engineers or other writers, GitHub's native review tools work well. The review experience breaks down with non-technical stakeholders: product managers, legal teams, subject matter experts, or clients who need to approve documentation before it goes live.

These reviewers rarely have GitHub accounts, and asking them to navigate a Markdown diff is a reliable way to get slow or incomplete feedback. The workaround most teams use is exporting to Google Docs, which creates version drift and manual reconciliation work.

DraftView gives these reviewers a different path. Connect your PR to DraftView, generate a review link, and share it with your stakeholders. They open a clean reading view of the rendered documentation in their browser, leave inline comments, and submit. Their feedback flows back into your PR as native GitHub Suggested Changes. No GitHub account required, no Markdown, no diff views.

Lint first to eliminate all style issues. Then get the right people to review the content. Keeping those two phases separate is what makes review cycles short.

Resources

• ProseLint Web: browser-based Vale linting for Markdown, AsciiDoc, MDX, and HTML
• AsciiDoc Alive: live AsciiDoc editor with real-time preview, no installation required
• Vale CLI: open-source prose linter for CI/CD integration
• Vale packages: official style guide packages from Microsoft, Google, Red Hat, and more
• Vale GitHub Action: automated linting in GitHub Actions