English for Vale Prose Linting

Vale applies linting concepts — rules, severity levels, style configs — to prose instead of code, and technical writers working alongside engineers benefit from using that shared vocabulary precisely, since it makes prose feedback feel as actionable as a code review comment. This guide covers the terms.

Key Vocabulary

Style — a named collection of rules (like Google’s, Microsoft’s, or a custom style) that Vale applies to a document, analogous to a linter’s rule set or config preset. “We’re extending the Microsoft style with a few custom rules rather than writing a style from scratch — most of their base guidance already matches what we want.”

Rule — a single check within a style, defined in a YAML file, that flags a specific pattern (passive voice, a banned term, an inconsistent capitalization) in prose. “This flag is coming from the ‘FirstPerson’ rule — we intentionally allow first person in tutorials, so we should scope that rule to exclude the tutorials directory.”

Severity level — the classification (suggestion, warning, error) assigned to a rule violation, determining whether it merely surfaces in output or actually fails CI. “Downgrade that rule’s severity to a warning instead of an error — it’s useful feedback, but it shouldn’t block a merge on its own.”

Vocab (vocabulary list) — a project-specific list of accepted and rejected terms (like approved product names or banned jargon) that Vale checks prose against, distinct from a general spell-check. “Add ‘Turbopack’ to the accepted vocab list — it’s a real product name, not a typo, and it keeps getting flagged.”

Scope (.vale.ini BasedOnStyles) — the configuration mapping specific file patterns or directories to which styles and rules apply, allowing different sections of docs to follow different conventions. “API reference pages are scoped to a stricter style than the blog — that’s intentional, since reference docs need more rigid consistency than narrative posts.”

Alert — the individual reported instance of a rule being triggered at a specific line and column, the actual output unit a writer sees and addresses, similar to a linter’s single flagged line. “There are only three alerts left in this document, and two of them are false positives from a rule that doesn’t understand code blocks correctly.”

Common Phrases

• “Is this flagged by a rule we actually want enforced, or should we exclude it for this file type?”
• “What severity is this rule set to — is it actually blocking CI, or just a suggestion?”
• “Is this term in the accepted vocab list, or is it genuinely a typo?”
• “Is this style scoped correctly, or is it applying to files it shouldn’t touch?”
• “How many alerts are real issues versus false positives from this rule?”

Example Sentences

Explaining a Vale configuration change in a PR: “I scoped the stricter terminology rule to just the reference docs folder — applying it to blog posts was producing too many false positives on intentionally informal writing.”

Reporting a false positive: “The passive voice rule is flagging a code comment inside a fenced block as prose — we should either exclude code blocks from that rule or lower its severity so it doesn’t fail CI.”

Discussing a style decision with a technical writer: “We’re extending the base style rather than writing everything custom, since most of the guidance around clarity and consistency already matches what we’d write ourselves.”

Professional Tips

• Reference the specific rule name when discussing a Vale alert — “the linter is complaining” is as unhelpful for prose as it would be for a code linter without a rule ID.
• Set severity levels deliberately and explain the reasoning in the config — a rule set to error without discussion tends to get silently disabled in frustration rather than fixed.
• Maintain the vocab list actively as product and tool names evolve — a stale vocab list generates noise that erodes trust in the linter’s other, genuinely useful alerts.
• Use scope precision when proposing a new rule — applying a style project-wide instead of to the specific doc type it’s meant for is a common source of over-flagging.

Practice Exercise

1. Explain in one sentence the difference between a style and a rule in Vale.
2. Write a PR description scoping a rule to a specific directory.
3. Describe, in your own words, what a vocab list is used for.