Proposal: Add "Changed headings?" to docs MR template / Documentation Guidelines
It seems that very few people outside of the docs team ever worries about the fact that changing headings will potentially break anchors. I've found some MRs where the only change was one heading name, which broke several anchors.
I propose two things:
-
Document that you must pay special attention when changing/deleting headings, as that may break anchor links in other docs. Where should this be added? -
Add one more review checkbox to the author's checklist, something like below (3rd item, just a first draft):
## Author's checklist
- [ ] Follow the [Documentation Guidelines](https://docs.gitlab.com/ee/development/documentation/) and [Style Guide](https://docs.gitlab.com/ee/development/documentation/styleguide.html).
- [ ] Link docs to and from the higher-level index page, plus other related docs where helpful.
- [ ] If any section heading (Ex: `## Heading Name`) was renamed or deleted, the project was searched for links to that heading from other docs (Ex: `[link text](../doc-name.md#old-heading-name)`), and updated accordingly.
- [ ] Apply the ~Documentation label