MR Approvals documentation Revamp
What does this MR do?
As part of #42651 (closed), this MR improves the JTBD of Create a merge request (Approval rules & Changing branches)
by completely revamping the documentation for Merge Request Approvals in a way that should make it much easier for first time users to understand and make use of the feature.
Revamped the Merge Request Approvals by:
- Substantial simplifications, clarifications and the kind of grammar touchups only an English teacher would be bothered by.
- Removing unneeded screenshots
- Reordering and grouping in a more logical way
- Fixing badges (if a page is badged at a certain tier, no need to rebadge sections if they are at the same tier)
- Moving sections out to related pages, and reducing duplication of information.
- Adding more in-page crosslinks.
- Naming sections in a more logical way that will make them more easily found by searching (SEO), as well as when looking at the TOC.
- Adding more section intros.
Layout
Before
After
Follow-Up
- Will raise a followup MR to fix the anchors in the code:
./ee/app/views/projects/merge_requests/_code_owner_approval_rules.html.haml: = link_to(_('Read more'), help_page_path('user/project/merge_requests/merge_request_approvals', anchor: 'code-owners-approvals-premium'))
./ee/app/views/projects/_merge_request_approvals_settings_form.html.haml: = link_to icon('question-circle'), help_page_path('user/project/merge_requests/merge_request_approvals', anchor: 'overriding-the-merge-request-approvals-default-settings'), target: '_blank'
Related issues
Related to #42651 (closed)
Author's checklist
-
Follow the Documentation Guidelines and Style Guide. -
If applicable, update the permissions table. -
Link docs to and from the higher-level index page, plus other related docs where helpful. -
Apply the documentation label.
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
-
Review by assigned maintainer, who can always request/require the above reviews. Maintainer's review can occur before or after a technical writer review. -
Ensure a release milestone is set. -
If there has not been a technical writer review, create an issue for one using the Doc Review template.
Edited by 🤖 GitLab Bot 🤖