Skip to content

Updates rules to reduce false positives (word choice, Latinisms, wordiness) #138

Merged
theletterf merged 1 commit into
mainfrom
issue-116
May 1, 2026
Merged

Updates rules to reduce false positives (word choice, Latinisms, wordiness) #138
theletterf merged 1 commit into
mainfrom
issue-116

Conversation

@jmikell821
Copy link
Copy Markdown
Member

Summary

Addresses feedback in #116 by removing Vale rules that had scope issues or produced false positives. Happy to discuss any of the following further if anyone disagrees.

Changes:

  • Removed since: because from Wordiness.yml — "since" isn't wordy; the concern is ambiguity between temporal and causal senses, which the pattern can't distinguish. Suggestions like "because version 8.0" are incorrect.
  • Removed see pattern from WordChoice.yml — "view" has the same sensory connotation as "see." WCAG's concern is about sensory-dependent instructions for identifying UI elements, not conventional cross-reference language.
  • Removed via: using from Latinisms.yml — "via" is a fully naturalized English word, not a Latin abbreviation. It carries a distinct meaning ("by way of") that "using" or "through" don't always capture.

Kept unchanged:

  • may: "can, might" — Already suggests both alternatives per Google's style guidance
  • Directional language guidance for "above/below" — Encourages precise references like "the following table"

Closes #116

Test plan

  • Run vale --config .vale.ini --no-global against sample files to verify rules no longer fire on removed patterns
  • Confirm remaining rules still function correctly

@github-actions
Copy link
Copy Markdown

github-actions Bot commented May 1, 2026

Vale Linting Results

Summary: 10 warnings, 10 suggestions found

⚠️ Warnings (10)
File Line Rule Message
.github/test-fixtures/sample-violations.md 7 Elastic.Articles Use 'an FAQ' instead of 'a FAQ'. The article depends on pronunciation, not spelling.
.github/test-fixtures/sample-violations.md 7 Elastic.Articles Use 'an HTML' instead of 'a HTML'. The article depends on pronunciation, not spelling.
.github/test-fixtures/sample-violations.md 7 Elastic.Articles Use 'an SQL' instead of 'a SQL'. The article depends on pronunciation, not spelling.
.github/test-fixtures/sample-violations.md 11 Elastic.BritishSpellings Use American English spelling 'optimize' instead of British English 'optimise'.
.github/test-fixtures/sample-violations.md 11 Elastic.BritishSpellings Use American English spelling 'customize' instead of British English 'customise'.
.github/test-fixtures/sample-violations.md 11 Elastic.BritishSpellings Use American English spelling 'behavior' instead of British English 'behaviour'.
.github/test-fixtures/sample-violations.md 27 Elastic.DontUse Don't use 'just'.
.github/test-fixtures/sample-violations.md 27 Elastic.DontUse Don't use 'please'.
.github/test-fixtures/sample-violations.md 27 Elastic.DontUse Don't use 'aka'.
.github/test-fixtures/sample-violations.md 35 Elastic.Articles Use 'an HTML' instead of 'a HTML'. The article depends on pronunciation, not spelling.
💡 Suggestions (10)
File Line Rule Message
.github/test-fixtures/sample-violations.md 15 Elastic.WordChoice Consider using 'efficiently' instead of 'Simply', unless the term is in the UI.
.github/test-fixtures/sample-violations.md 15 Elastic.WordChoice Consider using 'allowlist' instead of 'whitelist', unless the term is in the UI.
.github/test-fixtures/sample-violations.md 15 Elastic.WordChoice Consider using 'blocklist' instead of 'blacklist', unless the term is in the UI.
.github/test-fixtures/sample-violations.md 15 Elastic.WordChoice Consider using 'efficient' instead of 'easy', unless the term is in the UI.
.github/test-fixtures/sample-violations.md 19 Elastic.OxfordComma Use the Oxford comma in 'reading, writing and executing.'.
.github/test-fixtures/sample-violations.md 23 Elastic.Wordiness Consider using 'to' instead of 'In order to'.
.github/test-fixtures/sample-violations.md 23 Elastic.Wordiness Consider using 'because' instead of 'due to the fact that'.
.github/test-fixtures/sample-violations.md 23 Elastic.Wordiness Consider using 'many' instead of 'a large number of'.
.github/test-fixtures/sample-violations.md 31 Elastic.Exclamation Use exclamation points sparingly. Consider removing the exclamation point.
.github/test-fixtures/sample-violations.md 31 Elastic.Exclamation Use exclamation points sparingly. Consider removing the exclamation point.

The Vale linter checks documentation changes against the Elastic Docs style guide.

To use Vale locally or report issues, refer to Elastic style guide for Vale.

@theletterf theletterf merged commit 556d200 into main May 1, 2026
9 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Vale rules worth revisiting: four cases where scope could be narrower

2 participants