Issue trackers at ASTC (NSW) 2014

I’m attending the annual conference of the Australian Society for Technical Communication (NSW), ASTC (NSW) 2014. These are my session notes from the conference. All credit goes to the presenter, and any mistakes are mine. I’m sharing these notes on my blog, as they may be useful to other technical communicators. Also, I’d like to let others know of the skills and knowledge so generously shared by the presenter.

David Stephensen presented a session titled, “Issue trackers are not just for complaints and bugs”. The presentation covers the basic operation of issue trackers, uses of issue trackers and how to set them up for use in business, and ideas for the use of issue trackers in your work. This third aspect, David says, will hopefully be in our imagination as he talks.

Basic operation of issue trackers

An issue is a request for action – someone asking someone else to do something. David talked about 3 basic statuses: assigned, resolved, closed, plus the possibility of another status: reopened.

The roles define the players in the issue, including the reporter (person who raised the issue) and problem solver (the person who did the work). Another potential role is manager.

An issue tracker manages issues through the cycle of statuses. There are a number of issue trackers out there. David chose Mantis Bug Tracker, which is free and is known for being simple. It allows basic configuration, enough to make it useful in business.

What do you need of a bug tracker in business?

Recommended features in an issue tracker:

• Customisable workflow
• Custom fields
• Multiple projects
• Full text search

Plus desirable features:

• A plugin API
• Support for Unicode

Record keeping is paramount. You need an audit trail for meeting minutes, audit reports, and to act as a statement that an action was taken.

The case study

David walked us through the procedure of creating an issue for one of the projects he’s worked on.

First, a list of existing issues shows the status of each issue, colour-coded by status. The list also shows the issue ID, due date, category, reporter, and more fields. To report (create) an issue, there’s a generic form. You fill it in and hit submit. An issue is logged in the system and the assigned person receives an email.

Issue types may include:

• Request for service – please do something for me. Examples are maintenance requests and purchase requisitions.
• Problem report – please fix it.
• Something to record

For each issue type, it’s possible to add custom fields. That is, fields that are applicable to a particular type of issue. For example, for a maintenance request you may add a field to indicate severity, and another to indicate whether the problem has caused an injury or not. We saw an example of a maintenance request, noting that the lighting in a particular area (bay 6) needed fixing.

Another type of issue is a problem to be solved. There are 4 stages in a Corrective Action, and David showed us how he had included these stages in the issue tracker:

• Containing the problem
• Correcting the problem
• Finding the root cause
• Removing the root cause

The example was a person requesting that someone investigate the way an item was connecting with another. This was a preventive action, to ensure something doesn’t go wrong.

David demonstrated the third type of issue: something to record. This isn’t really an issue, but hi-jacking the issue tracker to ensure that you have a record of something, such as meeting minutes, audit reports, or a statement that action has been taken. The example was someone asking someone else to sign off on a review. Issue trackers have an indelible date stamp, which is very useful.

Following through on the lifecycle of an issue: People can add notes. It’s important for the problem solvers to report their progress, so that the report can see the updates. When the problem is fixed, you should resolve the issue on the tracker.

It’s possible to group issues into a project, which is useful for organising your issues. Being able to find issues is very important too, especially when there are 16000 issues on the tracker, as there were in the case studies. We looked at the filtering capabilities of the Mantis tracker, used to tailor search results. We also saw an example of the email notifications that the issue tracker sends when an event occurs, such as then an issue is assigned to you. You can also add yourself as a monitor of an issue, when you’re interested in receiving notifications about the progress on that issue.

A beautiful thing about issues is that everything that happens is recorded, and is visible in the issue history. David shows us an example, included the fact that files had been uploaded to the issue, it has been assigned, etc. The issue tracker display statistics, such as number of issues opened, resolved, or closed, and so on.

Getting a team to adopt an issue tracker

This can be tough. You need:

• Strong executive sponsorship
• Gradual introduction
• Training

Tip: Acquire some allies. Get people to reject things if they haven’t been reported properly. Ask problem solvers to refuse requests unless they’re in the issue tracker. Show and discuss the statistics during meetings.

Simplifying an issue tracker for use in business

David showed us some techniques for reducing the number of roles and statuses, and other features of the tracker. For business use, you don’t need all the features that are useful in software development. We ran out of time a bit here, so we had to go through the configuration rather fast.

Conclusion

It was interesting to see Mantis at work, and to see the case study of how an issue tracker was used in a specific environment. Thanks David for an excellent introduction to configuring and using an issue tracker.