Rename substitution-related Vale rules, add suggestion-level option

What does this MR do?

Capturing @sselhorn's thoughts from !187383 (merged):

Just to add another rule on a rule, we should try to use "because" instead of "as". Maybe you want to open another MR to add this to another Vale rule?

What I did here might sound like I overdid it a smidge, but let me narrate the steps:

  • Considered where to add the asbecause rule.
  • Wordy.yml? Not really. Hrm. One of the substitution rules?
  • Ugh, I know what SubstitutionWarning.yml is at a glance, but I can never remember if Substitution.yml is an error or a suggestion rule…
  • Huh, it's an error-level rule. So that means we don't have a suggestion-level substitution rule?
  • (renames ambiguous rule, creates new suggestion-level substitution rule)
  • (plays some Stevie Wonder because it's already in my head anyway)

…and that's how Substitution.yml became SubstitutionError.yml, and I am proposing SubstitutionSuggestion.yml. Any test for as will return false positives, so I won't bother proposing it any higher than this.

Result count

$ vale --no-wrap --filter='.Name=="gitlab_base.SubstitutionSuggestion"' **/*.md
  • 9,514 if we ignore case. (Ouch.)
  • 663 if we look for As and make it case-sensitive.

I have a feeling this is about to become a case-sensitive rule 😁

Related issues

Related to Adds 'you can' to Wordy.yml (!187383 - merged) because it came up in discussion.

Author's checklist

If you are a GitLab team member and only adding documentation, do not add any of the following labels:

  • ~"frontend"
  • ~"backend"
  • ~"type::bug"
  • ~"database"

These labels cause the MR to be added to code verification QA issues.

Reviewer's checklist

Documentation-related MRs should be reviewed by a Technical Writer for a non-blocking review, based on Documentation Guidelines and the Style Guide.

If you aren't sure which tech writer to ask, use roulette or ask in the #docs Slack channel.

  • If the content requires it, ensure the information is reviewed by a subject matter expert.
  • Technical writer review items:
    • Ensure docs metadata is present and up-to-date.
    • Ensure the appropriate labels are added to this MR.
    • Ensure a release milestone is set.
    • If relevant to this MR, ensure content topic type principles are in use, including:
      • The headings should be something you'd do a Google search for. Instead of Default behavior, say something like Default behavior when you close an issue.
      • The headings (other than the page title) should be active. Instead of Configuring GDK, say something like Configure GDK.
      • Any task steps should be written as a numbered list.
      • If the content still needs to be edited for topic types, you can create a follow-up issue with the docs-technical-debt label.
  • Review by assigned maintainer, who can always request/require the reviews above. Maintainer's review can occur before or after a technical writer review.
Edited by Amy Qualls

Merge request reports

Loading