Track TW development workflow with labels
Issue Description
To help us track team allocation as part of our reporting to UX and Eng Leadership, we need a single workflow that is an easily digestible view of the ongoing state of the TW team's issues and MRs. However, the implementation of the workflow needs to ensure it doesn't cause more work than the benefit it provides.
Proposal
Here is the proposed workflow, which is based on the use of scoped labels:
- An issue or MR is marked with the Technical Writing label in the usual manner.
- When the TW starts to work on the issue/MR, they add the
tw::doing
label. If the writer stops working on the unfinished issue/MR for more than two work days, they remove thetw::doing
label. If they restart their work, they restore thetw::doing
label. - When work is complete on the issue/MR, the TW adds the
tw::finished
label, which automatically replaces thetw::doing
label. - The issue/MR makes its way to Closed or Merged in the usual manner.
Separately, we'll create a Sisense dashboard to allow us, our stakeholders, and others the ability to see the work we have to do, what work we are doing, and what work we have done.
We can use the proposed labels together with group and stage labels to create a powerful view for PMs and other stakeholders. The dashboard will allow us all to quickly see the status of docs development across the team. PMs won't have to ask about the work going on. TWs can see what other writer might need some assistance.
If you want to view issues based on these labels before the Sisense dashboard is available, you can use the following search parameters to build searches or boards for yourself:
- Backlog: Open issues or MRs with the Technical Writing label.
-
Doing: Open issues or MRs with the
tw::doing
label. -
Finished: Open issues or MRs with the
tw::finished
label. - Closed: Closed or merged issues/MRs with the Technical Writing label.
Examples/Exceptions
What if I'm the TW that's merging the MR or closing the issue. Do I need to add the finished label?
In this case, there's no need to add the scoped workflow labels. Just ensure that the Technical Writing label is on the issue/MR, and that's enough. The tw::finished
label is for indicating when TW is done with issues/MRs for which we're not doing the merge or issue closing.
I fixed a typo, so it's not a lot of work, but I'm sending it along to another writer for review.
You should add the tw::doing
label to this item, as even though it's not a lot of work, you don't know when the reviewer will actually be looking at it and doing the review. Until then, as long as more than 2 workdays don't elapse, it's still "in progress."
The issue/MR was marked with the tw::finished
label, but now there's more work to do.
If you're presented with an open issue or MR for which you'd previously set the tw::finished
label but there's more to do, just add the tw::doing
scoped label to the issue/MR, and do the work to get it back to finished, and then merged/closed.
Actions
-
Add the following project labels to GitLab:
Label | Description |
---|---|
tw::doing |
The Technical Writing team is actively working on this item. (In Progress) |
tw::finished |
The Technical Writing team has completed its work on this item. |
-
Update the Technical Writing workflows Handbook page to include a section about our workflow label usage. -
Team starts using workflow procedure and labels to indicate their status for worked issues. -
Create initial dashboard (after coordinating with Data team, and getting labels into use) that describes the overall status of the team with the following columns: - Backlog (Open issues and MRs with the Technical Writing label, and no workflow labels).
- Doing (Open issues and MRs with the
tw::doing
label. - Finished (Open issues and MRs with the
tw::finished
label. - Closed (Closed issues and merged MRs with the Technical Writing label, probably from the last 2 weeks)