docs: address review — redundancy proof for Passive, wave-2 split, re-enable Contractions
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.
This commit is contained in:
parent
e9faa3896f
commit
115de60b09
3 changed files with 82 additions and 0 deletions
|
|
@ -67,3 +67,23 @@ jobs:
|
|||
# lint above pushes people toward, so the pointers need a gate of
|
||||
# their own. See scripts/check-doc-refs.sh.
|
||||
run: sh scripts/check-doc-refs.sh
|
||||
|
||||
prose-lint:
|
||||
name: prose lint (vale)
|
||||
runs-on: [hive-ci]
|
||||
# A `vale sync` + full docs/ run took under a minute in testing.
|
||||
timeout-minutes: 5
|
||||
steps:
|
||||
- uses: actions/checkout@v3
|
||||
- name: lint
|
||||
# Styles (Microsoft + alex + write-good, named in .vale.ini's
|
||||
# `Packages` line) are fetched fresh from the Vale Package Hub each
|
||||
# run rather than vendored, so this job always lints against
|
||||
# upstream's current rules. Failing red on a hit is intentional --
|
||||
# the existing docs/ tree has a real backlog against these rules
|
||||
# (663 hits as of this writing), so this job starts out red on
|
||||
# unrelated PRs until that backlog is worked down. Not (yet) wired
|
||||
# into branch protection as a required check, so a red result here
|
||||
# doesn't block a merge -- opting it into required-check status is
|
||||
# a separate, later call.
|
||||
run: XDG_DATA_HOME="$PWD/.vale-data" nix shell nixpkgs#vale --command sh -c 'vale sync && vale docs'
|
||||
|
|
|
|||
Loading…
Reference in a new issue