Skip to content

Add requirements for controlled docs reviewers (transparency say why not just, company announcements)

Michael Friedrich requested to merge controlled-docs-review-require-transparency into master

Why is this change being made?

There are increasing numbers of handbook MRs that lack transparency (examples in !125765 (merged) and https://gitlab.com/gitlab-com/www-gitlab-com/-/issues/34107) and miss to say why, not just what. Especially for controlled documents, transparency is required for team members to learn about changes async. Back and forth in Slack, and many different SSoTs is not transparent and inefficient, creating uncertainty.

We have discussed some ideas with codeowners review enforcements, following an update to update the review requirements for controlled documents. #32287 (comment 1378655775)

This MR adds requirements for reviewers of controlled documents that ensure that transparency is provided.

  1. Review for transparency, and say why not just what. (amended change for the title only in !127809 (merged))
  2. Review whether the change requires an announcement in Slack and the company newsletter.

The second MR !127693 (closed) for updating the default MR template for handbook updates helps this MR. It reminds team members who review MRs, about the procedure for all important changes, and links to the controlled documents review section (which is updated as part of this MR). Superseded by discussion for more efficient reviews in !127693 (comment 1497819705) with a new iteration MR in !127834 (merged)

This change warrants an update for all team members.

All MRs to help increase transparency

Related issues

  1. Updates to handbook pages which have a large im... (gitlab-com/content-sites/handbook#90)
  2. #32287 (comment 1378655775)

Author Checklist

  • Provided a concise title for this Merge Request (MR)
  • Added a description to this MR explaining the reasons for the proposed change, per say why, not just what
    • Copy/paste the Slack conversation to document it for later, or upload screenshots. Verify that no confidential data is added, and the content is SAFE
  • Assign reviewers for this MR to the correct Directly Responsible Individual/s (DRI)
    • If the DRI for the page/s being updated isn’t immediately clear, then assign it to one of the people listed in the Maintained by section on the page being edited
    • If your manager does not have merge rights, please ask someone to merge it AFTER it has been approved by your manager in #mr-buddies
    • The when to get approval handbook section explains the workflow in more detail
  • If the changes affect team members, or warrant an announcement in another way, please consider posting an update in #whats-happening-at-gitlab linking to this MR
    • If this is a change that directly impacts the majority of global team members, it should be a candidate for #company-fyi. Please work with internal communications and check the handbook for examples.
Edited by Michael Friedrich

Merge request reports