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.

Expanding Your Arsenal: Communicating Effectively with Vale

Vale is a fantastic tool – streamlining your code documentation and ensuring consistency across your project. However, even the best tools need clear communication to be truly effective. For non-native English speakers learning professional vocabulary within the context of software development, understanding how to use Vale and discuss its findings is just as important as knowing the technical details. It’s not enough to simply fix the linting issues; you need to articulate why those issues exist, what their impact might be, and how they relate to broader project goals. This often involves framing suggestions in a way that resonates with your team’s existing communication patterns and priorities.

Consider a scenario: You receive a comment on a pull request describing a style violation. The comment isn’t just “Fix this indentation.” Instead, it reads, “This section could benefit from more consistent spacing around the operators to improve readability for maintainers. Consider aligning with our team’s established style guide—we generally prefer 4 spaces.” This immediately adds context and justification. The language highlights a potential impact – improved readability – rather than just stating a rule. It also introduces the concept of a “team’s established style guide,” which is crucial for understanding where Vale fits within the larger development workflow. Similarly, in Slack conversations discussing Vale’s output, you might hear someone say, “I’m seeing a lot of these ‘minor’ violations – perhaps we should prioritize addressing them as part of our upcoming refactoring effort?” This demonstrates an ability to categorize issues by severity and connect them to strategic priorities. Understanding the nuances of phrasing like “minor,” “major,” or “recommended” is key, as these terms carry significant weight in discussions about prioritization and resource allocation.

Another common situation involves writing a PR description before submitting it. Instead of simply stating, “Vale linting passed,” you could write: “This PR includes updated documentation to adhere to Vale’s style guidelines, specifically addressing indentation and spacing concerns raised during the review process. The changes were made to improve code clarity and maintainability as per team standards.” This proactive approach demonstrates a commitment to quality and shows that you’ve considered the feedback provided by the linter. It frames the work not just as fixing errors but as actively contributing to a better codebase.

Finally, remember that Vale’s output provides data – information about what is wrong. You need to translate that data into actionable insights. Don’t just say “Vale flagged this.” Explain why it was flagged and what the potential consequences of ignoring it might be.

vale --config-file=my_vale_config.yaml .

This command, using a configuration file to tailor Vale’s behavior (e.g., specifying custom rules or severity levels), illustrates how you can subtly influence the communication coming from the tool – even before it generates its output. The my_vale_config.yaml file would contain settings that guide Vale towards your team’s specific needs and priorities, shaping the initial feedback to be more relevant and understandable for everyone involved.