docs(vale): prose burn-down toward gitlab-docs ideals (516 -> 217 findings)
What
Lift the reference prose toward GitLab documentation (vale) ideals using the reference's own report -> cutover -> enforce ratchet: vale stays advisory (the baseline is a visible backlog, not a gate), and we burn it down by category. Findings: 516 -> 217.
Phases in this MR
| Phase | Change | Result |
|---|---|---|
| 1 | airgapped -> offline environment (6 linted; identifiers/URLs/feature-names/design/ left) |
GitLab's preferred term adopted |
| 2 | term substitutions in prose: repo->repository, config->configuration, once the->after the, bullet->list item, causal since->because, log in->sign in, click->select; docs->documentation only in generic prose (the docs TEMPLATE name kept) |
~130 fixed |
| 3 | possessive rephrases (GitLab's X -> the GitLab X) where they read cleanly |
~20 fixed |
| 4 | de-tune the two voice rules the estate diverges on: NonStandardHyphens (en-dashes / -- in long prose) + LatinTerms (via), via the component's disable_rules. Required bumping vale@v3.3.0 -> v4.0.1 (where disable_rules + the ci-tools image-tag fix live), which also let us drop the earlier image override. validate-versions exempts vale's ahead-pin (like reference-check). |
168 silenced |
The remaining 217 (why we stop here, advisory)
~150 are correct usage vale flags as false-positives for this domain: within <time> SLA windows (changing to "in" loses precision), genuine future tense ("we will reach out"), the proper-noun docs template name, and possessives/antecedents that read worse stripped. The rest is a small mechanical tail + debatable style (Offerings self-managed, Simplicity, BoldEmphasis).
vale stays advisory. Enforcing now would red-wall CI on legitimate prose, and the false-positive-heavy rules (FutureTense, the within/docs substitutions) cannot be cleanly word-level de-tuned (disable_rules is whole-rule). The clear wins are captured; the residual is correct-as-is or a deliberate judgment call.
Pipeline green (vale advisory). Build green.
Draft for review.