Skip to content

Docs: Add Vale sentence spacing rule

What does this MR do?

This is a follow-up to !47136 (closed). There, I mentioned another "possibly … useful" reg-ex to find incorrect sentence spacing, which I suggest here. However, it doesn't seem to be very useful after all, because it matches just a few % more or less and different locations, counting the those as follows:

cd gitlab-org/gitlab/
git restore --source=3b90528db32cf3cda1d286344c36d3a409c18948~1 doc/*  # before gitlab-org/gitlab!23928

vale doc/ | grep 'must contain one' > vale-XYZ-rule.txt
# 3 times according to table below with different XYZ
# incomplete message from SentenceSpacing.yml because Vale output got broken into 2 lines, not sure why.

# also 3 times for the different XYZ
vale-XYZ-rule.txt | wc -l

# Cursory inspection of
diff vale-X-rule.txt vale-Y-rule.txt vale-Z-rule.txt
Results
This rule N hits
not added 208
added as 3rd 207
replacing 1st 200

Because of this low difference, and

  1. #199367 (closed) & its follow-up MRs cleaned up the majority of hits already, and
  2. seeing the risk of leaving a few typos and such in our docs as actually an opportunity to remain open for "legitimate peripheral participation",

I would not change the Vale rule after all and close this MR. To me, it seems my assumption in !47136 (closed) was prematurely optimistic 😅 I also cancelled the pipeline for this reason.

However, I'm sure you know better testing regimes for the quality and usefulness of such a reg-ex / rule, so please feel free to take over this MR if you see potential.

Related issues

&2497 (closed) & #199367 (closed).

Author's checklist (required)

When applicable:

Review checklist

All reviewers can help ensure accuracy, clarity, completeness, and adherence to the Documentation Guidelines and Style Guide.

1. Primary Reviewer

  • Review by a code reviewer or other selected colleague to confirm accuracy, clarity, and completeness. This can be skipped for minor fixes without substantive content changes.

2. Technical Writer

  • Optional: Technical writer review. If not requested for this MR, must be scheduled post-merge. To request for this MR, assign the writer listed for the applicable DevOps stage.

3. Maintainer

  1. Review by assigned maintainer, who can always request/require the above reviews. Maintainer's review can occur before or after a technical writer review.
  2. Ensure a release milestone is set.
  3. If there has not been a technical writer review, create an issue for one using the Doc Review template.
Edited by Katrin Leinweber

Merge request reports