Skip to content

MR Approvals documentation Revamp

Marcel Amirault requested to merge docs-mr-approvals into master

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

Screen_Shot_2020-01-29_at_2.33.48

After

Screen_Shot_2020-01-29_at_2.33.34

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

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 🤖 GitLab Bot 🤖

Merge request reports