Documenting Known Issues

girl-with-objects-around-her-by-oblik-st

Improving the process for documenting known issues and workarounds through better tracking.

Role: Lead writer

Tools: Jira and Confluence

Skills: Project management, critical thinking

Team size: 1

Outcome: Decreased writer effort by 23%

⚠️

CHALLENGE

Tracking and documenting known issues for scheduled releases was a time-consuming effort. Engineering stories were not maintained in a single place and were difficult to locate.

Additionally, keeping track of what had already been documented as new issues were discovered and added to the list became confusing, and caused writers to waste time determining if an issue was already documented.

💡

SOLUTION

Create a system for tracking documentation status for known issues that is visible to both the writer and their stakeholders.

💬

PROCESS

1. Putting it all in one place

This first challenge to tackle was determining where to track all known issues and workarounds in one place. Both the engineering and writing teams use Confluence, so I created a page under our release tracker.

Within this page, I added Jira filters for issues tagged for the current release. After some consideration, this became three filters:

New issues created in this release
New issues that have workarounds available
Legacy issues discovered during QA

Legacy issues are documented separately from issues created during a release, so these stories were added to a separate documentation task.

However this didn't solve the problem of tracking writer status, just developer status. For this, we needed to create a backlog.

2. Creating a backlog

While Jira provides a backlog for projects, I needed something more specific. I needed to separate out each filter into two lists:

Backlog: newly tagged as known issue, not documented.
Complete: added to documentation for the release.

To accomplish this, I needed to tag each issue with a parameter I could use to adjust my filters.

After confirming with the engineering lead, QA, and PM for the product, I created a new label: TW_complete.

I then duplicated each filter. The filter for my backlog tracked issues that did not include this label, whereas the filter for complete issues tracked those that did include it.

Here is an example of each filter type, using JQL (Jira Query Language).

Backlog

issuetype = Bug AND project = KEY AND label = release_known_issue AND label != TW_complete

Complete

issuetype = Bug AND project = KEY AND labels in (release_known_issue, TW_complete)

3. Marking an issue as complete

To mark an issue as complete, the writer would add the label TW_complete to the ticket.

When the filters automatically refreshed, the issue would move from the backlog to complete.

✔️

IMPLEMENTATION

After implementing this process, the writer effort for documenting known issues decreased by 23%.

This metric was determined by calculating the difference in time logged for writing, reviewing, and publishing the known issues between two releases of similar intensity.