81 lines
4.3 KiB
INI
81 lines
4.3 KiB
INI
# `StylesPath` is not set here: the `vale` package in nix/packages/vale.nix
|
|
# prepends it, pointing at the pinned styles in nix/packages/vale-styles.nix.
|
|
# A style enabled below must also be listed there.
|
|
MinAlertLevel = warning
|
|
|
|
[*.md]
|
|
BasedOnStyles = Microsoft, alex, write-good
|
|
# Gated on CI once the existing backlog of write-good.Passive hits cleared
|
|
# to zero — every remaining hit at the time of this flip is a reviewed
|
|
# false positive, individually wrapped in a scoped
|
|
# `<!-- vale write-good.Passive = NO/YES -->` pair rather than bulk-ignored.
|
|
write-good.Passive = error
|
|
|
|
# --- Rules disabled against evidence from our own docs/ tree, not guessed ---
|
|
#
|
|
# Domain-vocabulary mismatches -- Microsoft's own product-terminology and
|
|
# audience assumptions don't fit this repo, not a style call:
|
|
#
|
|
# Wants "agent" replaced with "personal digital assistant" (Microsoft's
|
|
# assumed product context, not ours -- "agent" is core hyperhive vocabulary).
|
|
Microsoft.Terms = NO
|
|
# "URL" is exactly the right word for people configuring DNS and TLS;
|
|
# "use 'address' for a general audience" doesn't fit this audience.
|
|
Microsoft.GeneralURL = NO
|
|
# Empirically 100% redundant with write-good.Passive (kept, below): diffed
|
|
# the exact file:line:col locations each one flags on the full docs/ tree --
|
|
# 726/726 identical, zero difference either direction. Running both doubles
|
|
# the count for no extra coverage; keeping write-good's copy since
|
|
# write-good is the agreed base style, not a judgment that Microsoft's
|
|
# version is worse.
|
|
Microsoft.Passive = NO
|
|
# Fires on every spaced em-dash (' — ', ~2000 occurrences across docs/).
|
|
# Not a defensible "this repo chose this style" claim -- it's an incidental,
|
|
# emergent convention nobody deliberately picked, not a deliberate one worth
|
|
# defending. Disabled because retrofitting ~2000 existing occurrences is out
|
|
# of scope for a lint-adoption PR, not because the convention is correct.
|
|
Microsoft.Dashes = NO
|
|
|
|
# --- Wave 2 candidates: disabled for this initial rollout, not dismissed.
|
|
# Each needs either false-positive-rate data from a real pass, or an actual
|
|
# rewrite pass through the flagged headings/words -- both real follow-up
|
|
# work, not a permanent call:
|
|
#
|
|
# "Remove the adverb if it's not important to the meaning" needs a human
|
|
# judgment call per hit; revisit once we know the real false-positive rate.
|
|
Microsoft.Adverbs = NO
|
|
# Flags ordinary systems/ops vocabulary (destroy, crash, failure, hook) as
|
|
# "profane in some cases" -- miscalibrated for an engineering docs repo as
|
|
# shipped, but alex's other inclusive-language rules stay enabled below.
|
|
alex.ProfanityUnlikely = NO
|
|
# Fires on every form of "to be" (is/are/be/aren't/...); needs the same
|
|
# false-positive-rate pass as Adverbs before it's worth turning on for real.
|
|
write-good.E-Prime = NO
|
|
# Heading acronyms (MCP, CI, API, TLS, ...) are common in this tree, but
|
|
# that's not proof they're not worth spelling out -- e.g. "setting up
|
|
# transport encryption" instead of "setting up TLS" is a real improvement.
|
|
# Needs an actual rewrite pass through the flagged headings, not a blanket
|
|
# call either way.
|
|
Microsoft.HeadingAcronyms = NO
|
|
|
|
# --- Ruled on, not wave 2 -- disabled for good, not pending a follow-up pass ---
|
|
#
|
|
# Flags this repo's own consistent sentence-case heading convention
|
|
# ("### Current limitation: state-dir visibility lags topology") for not
|
|
# capitalizing after the colon. Same shape as Microsoft.Dashes above: a
|
|
# real house-style conflict, not a defect. Ruled to keep the house style.
|
|
Microsoft.HeadingColons = NO
|
|
# Checked every real hit on our docs/ tree: zero true positives. It fires
|
|
# on the word "percent" used as an identifier (`cpu.percent`, "percent
|
|
# resolver"), never on an actual spelled-out percentage. A rule with no
|
|
# observed true positive on this corpus isn't worth keeping enabled.
|
|
Microsoft.Percentages = NO
|
|
# Checked all 114 hits by hand, not sampled: every single one flags a
|
|
# precise, normal technical/formal word from write-good's default
|
|
# corporate-bloat wordlist ("validate", "monitor", "therefore",
|
|
# "however", "multiple", ...), not an actual verbose phrase -- none of
|
|
# the genuinely wordy multi-word bloat this rule exists to catch ("due
|
|
# to the fact that", "in order to", "at the present time") appears even
|
|
# once. Rewriting precise vocabulary into vaguer prose to satisfy a
|
|
# dictionary mismatch would make the docs worse, not better.
|
|
write-good.TooWordy = NO
|