Skip to content

Automate application of the Technical Writing label to MRs approved by Technical Writing team members

Summary

We're missing the Technical Writing label on quite a few MRs each milestone where it should be applied. It's a manual process at the moment. We'd like to look at how we could automate it. When we miss adding the Technical Writing label, it has an impact on key metrics (see Why it matters below)

Why it matters

The Technical Writing label is fundamental to the following metrics:

  • UX KPIs, Technical Writer MR rate. As our team has grown, the average monthly MR rate has decreased. There are a number of factors that influence this trend, including the Development Department MR rate, an expanded scope of complexity of work (refactoring, tutorials, and UI text), and onboarding of new team members.
  • Stage and group MR and issue tracking. Groups have varying demands on the technical writing team. We reorganize semi-frequently because our TW team does not yet meet our gearing ratio (1 writer, 3 groups), and we must rebalance the workload. Accurately tracking the Technical Writing team involvement per Group helps inform group rebalancing efforts (example).

By relying on manual application of the label, it can easily get missed off MRs (and issues). This can lead to underreporting in the above metrics.

Label definition and usage

The Technical Writing label is defined as:

Epics, issues, and merge requests with Technical Writing team input.

In our Usage guidance in the handbook we say:

Any issue or merge request for which a Technical Writer provides a measurable amount of work on (including content creation and reviews) must include the Technical Writing label.

MVC implementation

A suggestion for an MVC to add automation could be:

Any MR where Approved-by OR merged by=a member of gl-docsteam gets the Technical Writing label applied if it is not already on there.

If we wanted to try this out in a subset of projects - perhaps gitlab and gitlab-development-kit.

Projects where Technical Writing team members work:

Notes from issue triage-ops issue template

  • Automation that does not require an assignee.
    • Rescheduling of milestones (milestone refinement)
    • Labelling missed-deliverable and missed:x.y based on the scheduled milestone.
    • Labelling ~"bug" on regression and on regression:x.y.
    • Labelling priority1 and severity1 on master:broken.
    • Labelling SLOMissed on issues with ~"bug" past SLO priority target.
    • Discovery of potential and popular proposals.
    • Remind people to add labels if an issue has no labels.
  • Triage reports
    • Untriaged issue triage reports, please list assignee: ASSIGNEE_NEEDED
    • Community Merge Requests, please list coaches: COACHES_LIST
    • Group triage reports
  • WIP: Infer stage and group labels from subject labels
Edited by Diana Logan