Add vale rule to enforce ordering of history and details

What does this MR do?

As reported in the related comment, it's easy to accidentally put the DETAILS: and History items in the wrong order, so we should use Vale to enforce this. This rule found one new example in the docs, which was added recently, which is a good indicator that we need the rule.

Related issues

• Related to !147964 (comment 1832943498)

Author's checklist

• Optional. Consider taking the GitLab Technical Writing Fundamentals course.
• Follow the:
  • Documentation process.
  • Documentation guidelines.
  • Style Guide.
• If you're adding a new page, add the product tier badge under the H1 topic title.
• If you are a GitLab team member, request a review based on:
  • The documentation page's metadata.
  • The associated Technical Writer.

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.

changed milestone to %16.11

added Technical Writing devopscreate docs-linting docsimprovement documentation groupcode review maintenancerefactor tw-testing typemaintenance vale labels

requested review from @sselhorn

assigned to @marcel.amirault

added sectiondev label

@sselhorn I was able to figure out a rule for this, hopefully that works for you too.

I looked at !147963 (comment 1832940899) too, but I don't think we can easily lint for it, that one is a bit too hard/specific. Hopefully it doesn't happen much

	1 Message
	This merge request adds or changes documentation files. A review from the Technical Writing team before you merge is recommended. Reviews can happen after you merge.

Documentation review

The following files require a review from a technical writer:

• doc/.vale/gitlab/HistoryItemsOrder.yml (Link to current live version)
• doc/user/project/merge_requests/changes.md (Link to current live version)
• doc/user/project/requirements/index.md (Link to current live version)

The review does not need to block merging this merge request. See the:

• Metadata for the *.md files that you've changed. The first few lines of each *.md file identify the stage and group most closely associated with your docs change.
• The Technical Writer assigned for that stage and group.
• Documentation workflows for information on when to assign a merge request for review.

Reviewer roulette

Category	Reviewer	Maintainer
/doc/.vale/	Reviewer review is optional for /doc/.vale/	@kpaizee (UTC+2, 7 hours behind author)

Please check reviewer's status!

• Reviewer is available!
• Reviewer is unavailable!

Please refer to documentation page for guidance on how you can benefit from the Reviewer Roulette, or use the GitLab Review Workload Dashboard to find other available reviewers.

If needed, you can retry the danger-review job that generated this comment.

Generated by Danger

changed the description

added docs-only label

added 1 commit

• 8f3c085c - Remove superfluous note

Compare with previous version

added 1 commit

• f9733555 - Apply 3 suggestion(s) to 2 file(s)

Compare with previous version

approved this merge request

resolved all threads

enabled an automatic merge when the pipeline for 1bfba83f succeeds

Thank you so much @marcel.amirault Nice work. I applied a few tiny nitpicky suggestions, tested locally, and merged.

If/when you have time, can you add these history/details rules to all the doc repos?

merged

cc: @dianalogan FYI--adding one more Vale rule to test version history/DETAILS sections. Some of them were out-of-order so they rendered strangely.