Documentation pull requests have a quality problem that no team likes to admit. The reviewer is usually a senior engineer who is qualified to judge whether the code change is correct, but is not paid to catch comma splices, subject-verb disagreement, or wordy nominalizations in the README diff. Either the doc gets merged with rough prose because the reviewer is being polite, or it gets stalled for a week while a different reviewer who cares about grammar makes a pass. Neither outcome is good.
This guide walks through a documentation grammar workflow that adds one minute to a normal PR review and catches the common errors that would otherwise either ship or block the merge.
The Problem in Concrete Terms
A typical docs PR looks like this. The author opens a PR that updates the migration guide, adds an architecture explainer, or revises the API reference. The diff is 200 to 800 lines of prose. The reviewer is whoever has context on the underlying system. The reviewer reads for technical accuracy and skims for obvious prose problems. The result is that grammar errors slip through at a rate of one or two per substantive page.
This is fine for internal-facing docs. It is not fine for customer-facing API documentation, getting-started guides, or anything that shows up in search results and represents the project's professionalism. The fix is to add a grammar pre-check that runs before the human review even starts.
Step 1: Pick a Tool That Runs Locally or In CI
Grammar checkers fall into two categories: editor plugins that run in the IDE while the author is drafting, and CLI tools that can run in CI. Both have a role. Editor plugins catch errors at draft time. CLI tools catch errors that slipped past the draft, including the ones the author dismissed because the underlines were annoying.
The CLI tools worth a look in 2026 are LanguageTool's self-hosted server, Vale, alex, and write-good. Each has a different niche.
- LanguageTool has the broadest grammar rule coverage but needs a JVM and a few hundred megabytes of RAM. Best run as a local service.
- Vale is style-guide-driven and Markdown-aware out of the box. Best when the team wants to enforce a specific style guide.
- alex catches inconsiderate language and inclusive-writing problems. Different niche than grammar checking, but worth combining.
- write-good is a Node-based passive-voice and weasel-word checker. Lightweight, opinionated, fast.
The browser-based AI Grammar Checker is useful for one-off draft passes and for review situations where a reviewer wants to paste a section and read the flags without installing anything. It does not replace the CI step.
Step 2: Wire the Tool Into the PR Workflow
The CI step needs three properties to not waste the team's time.
First, it has to run only on changed files. A docs repo with 200 markdown pages cannot afford a full sweep on every PR. Use the git diff to limit the check to files touched in the branch.
Second, it has to fail loud on real errors and quiet on stylistic flags. Grammar errors (subject-verb disagreement, homophone misuse, comma splices) should block the merge. Stylistic suggestions (passive voice, sentence length, weak verbs) should be advisory comments, not blocking.
Third, it has to respect per-document overrides. Methods sections, code samples, and fenced quoted text often legitimately violate the prose rules. The tool needs a way to skip these blocks. Vale does this with frontmatter directives. LanguageTool does it with inline comment markers. Choose a tool that supports the skip syntax you can teach your authors to use.
A simple GitHub Actions workflow looks like:
name: docs-grammar
on:
pull_request:
paths: ['docs/**/*.md', 'README.md', '*.mdx']
jobs:
grammar:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
with:
fetch-depth: 0
- name: Get changed markdown files
id: changed
run: |
git diff --name-only origin/main...HEAD -- '*.md' '*.mdx' > changed.txt
cat changed.txt
- name: Run grammar check
run: |
while read file; do
languagetool-cli --language en-US --disable-categories STYLE \
"$file" || true
done < changed.txt
The STYLE category disable is the key line. It turns off passive-voice flagging and the other stylistic suggestions that would otherwise overwhelm the reviewer.
Step 3: Decide Which Suggestions Block the Merge
A grammar check that fails on every stylistic flag will be turned off within a week. A grammar check that fails on nothing will be ignored. The middle is failing on a tight list of categories.
The categories worth blocking on are:
-
GRAMMAR, for subject-verb agreement, tense consistency, and pronoun reference -
TYPOGRAPHY, for comma splices, run-on sentences, and doubled punctuation -
CONFUSED_WORDS, for homophones and common misspellings of similar-sounding words -
REPETITIONS, for repeated words from cut-and-paste edits
The categories worth surfacing as advisory comments rather than blocking are:
-
STYLE, for passive voice, sentence length, weak verbs, and nominalizations -
REDUNDANCY, for wordy phrasings that could be tightened -
TYPOS, for when the tool's dictionary does not include the project's product names
The blocking categories are the ones where a human reader would call the result a "mistake." The advisory categories are the ones where the result might be intentional. The reviewer can choose to enforce the advisory items selectively.
For background on why passive voice deserves to stay in the advisory bucket rather than the blocking one, see the longer piece on why grammar checkers flag passive voice even when it is the right choice. The short version is that pattern-based passive detection produces too many false positives in technical writing to be a hard fail.
Step 4: Train the Authors to Ignore the Right Flags
The team needs to know which flags to fix and which to ignore. The training is a five-minute walkthrough at a team meeting plus a one-page reference in the docs repo.
The reference should answer four questions:
- Which categories block the merge?
- How do I skip a flag on a sentence the tool is wrong about?
- How do I add a project term to the dictionary so the tool stops flagging it?
- Where do I run a local check before pushing?
That last item matters. A grammar check that only runs in CI catches errors after the author has context-switched out of the doc. A local pre-commit hook or editor plugin catches them at draft time, when the fix takes ten seconds. Both layers should be in place.
EvvyTools collects related writing helpers, including the AI Grammar Checker, in a single tools directory that is handy for the one-off draft passes that do not need a full CI setup.
Step 5: Measure the Impact
A grammar check workflow is worth keeping only if it catches errors that would otherwise ship. Once a quarter, take a sample of merged PRs and count grammar errors that the check did not catch. If the count is low, the workflow is doing its job. If the count is high, the rule configuration is too loose. Adjust and rerun.
The second metric worth tracking is PR cycle time. A grammar check that adds ten minutes to a typical PR review is a net loss even if it catches errors, because the team will stop opening docs PRs. A grammar check that adds under a minute is a net win. The numbers come from the team's GitHub or GitLab analytics.
The right balance is a CI step that runs in under thirty seconds, fails on a tight set of blocking categories, and surfaces the rest as comments the reviewer can choose to enforce. That setup catches the errors that matter without becoming the new bottleneck.
For background on why grammar checkers are still imperfect tools and how to read their suggestions in any draft genre, the longer guide on why grammar checkers flag passive voice even when it is the right choice covers the underlying logic. The Vale documentation site, the LanguageTool homepage, and the GitHub Actions docs are the three best references for the CI side of the workflow. For lighter-weight one-off draft passes, the writing tools at EvvyTools cover the same ground without the CI infrastructure overhead.
Top comments (0)