115de60b09
mara's review, addressed with evidence not assertions: - Microsoft.Contractions: re-enabled per her flat disagreement, no argument. - Microsoft.Passive vs write-good.Passive: she asked what the difference actually is. Ran both individually against the full docs/ tree and diffed the exact file:line:col sets -- 726/726 identical, zero difference either direction. Genuinely redundant, not assumed. write-good.Passive stays enabled (agreed base style), Microsoft.Passive drops as the literal duplicate. - write-good.Passive: she disputed my invented examples (correctly -- a clean single-actor rewrite does read better active). Pulled 10 real hits from the actual docs tree instead of inventing more sentences; most have a generic/implicit actor where passive reads naturally, not a clear active-voice win. Re-enabled per the redundancy point above rather than disabled as "mostly noise". - Microsoft.Dashes: same outcome (stays disabled, retrofitting ~2000 existing occurrences is out of scope here) but the reasoning was wrong -- not a "deliberate convention", an incidental one nobody chose. Rewritten. - Microsoft.Adverbs, alex.ProfanityUnlikely, write-good.E-Prime, Microsoft.HeadingAcronyms: moved to an explicit "wave 2 candidates" section -- disabled for this rollout, not dismissed. Each needs a real false-positive-rate pass or an actual rewrite pass through the flagged instances before a permanent call. - Dropped the .vale.ini header's pointer to "the PR description" for rationale -- not durable/visible enough as a reference from a file that lives in the repo. Rationale is now fully inline per rule. 1069 more hits than the previous round (726 write-good.Passive + 343 Contractions, Microsoft.Passive's 726 removed) -- 1732 total across 50 files.
60 lines
3.1 KiB
INI
60 lines
3.1 KiB
INI
# `vale sync`'s destination isn't actually governed by this path -- it
|
|
# always writes under `$XDG_DATA_HOME/vale/styles` (undocumented, confirmed
|
|
# by testing: neither this file's discovery nor `--config` affects it). Set
|
|
# `XDG_DATA_HOME=$PWD/.vale-data` before running `vale sync`/`vale docs` so
|
|
# both commands agree on the same repo-local, gitignored location.
|
|
StylesPath = .vale-data/vale/styles
|
|
MinAlertLevel = warning
|
|
# `vale sync` reads this to know what to fetch from the Hub at CI time --
|
|
# styles are fetched fresh each run, not vendored into the repo.
|
|
Packages = Microsoft, alex, write-good
|
|
|
|
[*.md]
|
|
BasedOnStyles = Microsoft, alex, write-good
|
|
|
|
# --- 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
|