Skip to content

Make documentation a throughput label

Marcel Amirault requested to merge docs-only-throughput-label into master

What does this MR do?

Edit: Changed the throughput label from docs-only to documentation. See discussion below.

Previous description.

I have created an MR to update the handbook to reflect this as well: gitlab-com/www-gitlab-com!42417 (merged)

This makes docs-only a throughput label for Danger. I think it makes sense to separate out ~backstage changes to the codebase from docs-only changes. According to the documentation on backstage throughput:

  • it is the work we do to keep the product running smoothly or our own development running smoothly. Technical debt is under this category, though to keep the categories simple, we currently do not use the ~"technical debt" label. Please use ~"backstage" instead.

Changes to our pipelines, Danger, refactoring/cleaning up code and specs, and all other general improvements are significantly different than "Fixing a typo", and I think we should be clear about that. This will make the ~backstage label more useful as well, IMHO, as all the minor docs changes will now be excluded.

For example, this MR is exactly the type of MR that is ~backstage, as it is tweaking Dangerbot.

If I was fixing a Typo, it would make more sense to call it docs-only and omit ~backstage. It makes more sense for other non-feature docs housekeeping tasks as well (fixing broken links, adjusting markdown standards, reordering a page, etc).

The main benefit: it's more logical for everyone for documentation changes. Many people already add docs-only to "docs-only" MRs, only to have Danger bot complain that there is no throughput label. Also, the description of ~backstage does not match docs-only changes, IMHO: Issues and merge request related to improvements like refactorings, test, maintenance etc. I think we started using ~backstage purely because we had to add a throughput label, and it was the "least bad" option, not the best option.

I also think it would be useful/logical to track how much work is done on "docs-only" changes by the Technical Writing team, which is separate from "true backstage" changes the technical writing team does: Updating our pipeline/images, changing codeowners, fixing UI docs links, tweaking Dangerbot, etc. Additionally, docs-only is applied unevenly, as it's not a strict requirement, so this will help stabilize reporting too.

We have already removed docs-only changes from the Changelog check, in (#37340 (closed)), and this is the logical next step.

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