Start with expensive mistakes

A style linter can check thousands of sentences in seconds, which makes it tempting to encode every editorial preference. Resist that temptation. The best first rules catch problems that are costly to review manually: banned product names, inconsistent terminology, exclusionary language, ambiguous warnings and repeated formatting errors.

If the first run produces hundreds of low-value warnings, contributors learn to ignore the tool before it has earned trust.

Treat rules as code

Keep the Vale configuration and vocabularies in the repository. Review changes to them. Give custom rules names that explain intent, not just implementation. A rule called ApprovedProductNames is easier to discuss than RegexRule17.

Add a small fixture set with examples that should pass and fail. When a rule changes, the expected behavior should change with it.

Separate errors from advice

Only block a build for issues the team agrees must be fixed. Use warnings for patterns that require judgment. A sentence can be passive for a good reason; an obsolete trademark spelling is usually less negotiable.

This distinction keeps CI useful. Writers should be able to predict which findings are publication blockers.

Tune the vocabulary

Terminology is where a linter often provides the fastest return. Maintain approved names, capitalization and replacements centrally. Add product-specific exceptions explicitly instead of disabling useful rules globally.

Review false positives as signals. Sometimes the rule is wrong; sometimes the content model is making a legitimate term difficult to express consistently.

Keep human editing human

Vale cannot decide whether an explanation answers the reader’s real question, whether information appears in the right place, or whether an example teaches the correct mental model. Use automation for repeatable defects and spend editorial attention on structure, evidence and clarity.

A good quality gate is almost boring: it catches the same important mistakes every time and rarely surprises the author.

Applied example

Treat “Use Vale as a quality gate, not a punctuation police force” as a small evaluation, not a feature-list comparison. Choose three representative content samples from your own work: one simple page, one page with code or structured data, and one awkward page with navigation, reuse or localization requirements. Run all three through the tool or method and record what becomes easier and what new maintenance cost appears.

Judge the result on work your team will repeat every week:

  • Can an author understand the source without specialized knowledge?
  • Can a reviewer see a meaningful diff?
  • Can the build fail with an error that points to a fixable problem?
  • Can content be moved, localized or reused without manual cleanup?

Do not reward a tool for producing an impressive demo that your real content cannot sustain. A good documentation tool reduces uncertainty in authoring, review and publishing. If it shifts complexity into hidden configuration, fragile plugins or one expert’s memory, include that cost in the decision.

Quick editorial checklist

  • Start with expensive mistakes. A style linter can check thousands of sentences in seconds, which makes it tempting to encode every editorial preference.
  • Treat rules as code. Keep the Vale configuration and vocabularies in the repository.
  • Separate errors from advice. Only block a build for issues the team agrees must be fixed.
  • Tune the vocabulary. Terminology is where a linter often provides the fastest return.