Skip to content

Revamp Merge Request documentation

Marcel Amirault requested to merge docs-merge-requests-1 into master

What does this MR do?

Merge Request documentation needs a full revamp. It's a fundamental part of working with GitLab, but the barrier to entry is quite high. As identified in &1678 (closed), this is a weakness in our documentation.

Changes

  • Make the index page a better landing page for those who are new to GitLab and merge requests, separating out the feature documentation to different pages:
    • Features already listed on their own page will remain unchanged.
    • Links out to documentation for MR-related features grouped in tables based on:
      • Creating MRs
      • Reviewing/Managing MRs
      • Reports displayed in MRs (ex: testing)
    • Features described in the index moved to:
      • new creating_merge_requests.md
      • new reviewing_and_managing_merge_requests.md
  • Remove all tiny sections that do nothing but link to another page.

Phase 2 (another MR): Add an expanded intro to the Reviewing/Managing MRs doc.

Phase 3 (another MR) to evaluate the old content itself, and check the if more information can be combined, or if other changes should be made. The top image should be re-evaluated as well.

Current Status

  • The MR doc index was cut from 600+ lines to <120 lines. "Doubly linked" things (links from the top that go to the middle of the index, only to link again to another page) are removed.
  • Anything related to creating MRs is on a new page with a new intro and basic MR details that didn't seem to exist anywhere at all. Nesting of these sections improved as well.
  • Anything related to reviewing/managing MRs is on another new page. Less work on this since it's not the OKR focus. Will expand intro and add more details in a follow-up MR. No information was lost.
  • The massive list near the top of the index completely removed, and added into the three tables of easy-to-read details, which will be easier to maintain as new features are added.
  • The feature content is unchanged.
  • The new content is mostly introductory sections for:
    • creating_merge_requests.md (from top to ## assignee)
    • reviewing_and_managing_merge_requests.md (short intro at top)
    • Simple intro for index.md and for the 3 new sections.

Review notes:

All the content relating to features themselves (that were moved into the two new pages) was untouched except to fix links.

The reviewer should focus on:

  • whether or not the new locations for the features make sense
  • review the new text:
    • Table content (descriptions taken from list in previous MR doc)
    • Intros to the new pages, and the new sections in the index.

Related issues

Related to #31708 (closed)

Changes as seen in TOC

(minor changes since this image was added, but generally the same)

MR-revamp-TOC

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 and that you merge the equivalent EE MR before the CE MR if both exist.
  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