Updates rules to reduce false positives (word choice, Latinisms, wordiness) #138
Merged
Conversation
Vale Linting ResultsSummary: 10 warnings, 10 suggestions found
|
| 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
approved these changes
May 1, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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:
since: becausefromWordiness.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.seepattern fromWordChoice.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.via: usingfromLatinisms.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 guidanceCloses #116
Test plan
vale --config .vale.ini --no-globalagainst sample files to verify rules no longer fire on removed patterns