TechWhirl (TECHWR-L) is a resource for technical writing and technical communications professionals of all experience levels and in all industries to share their experiences and acquire information.
For two decades, technical communicators have turned to TechWhirl to ask and answer questions about the always-changing world of technical communications, such as tools, skills, career paths, methodologies, and emerging industries. The TechWhirl Archives and magazine, created for, by and about technical writers, offer a wealth of knowledge to everyone with an interest in any aspect of technical communications.
Subject:Re: Bug tracking and documentation From:Stuart Burnfield <slb -at- westnet -dot- com -dot- au> To:Techwr-l <techwr-l -at- lists -dot- techwr-l -dot- com> Date:Thu, 14 May 2009 13:15:28 +0800 (WST)
Hi Julie -
My company is switching to a new tracking system, Jira. It looks to be good and very flexible if you have a bit of programmer time available to customise it to your reqs. You can set up up different workflows based on the type of issue. What this means is that there are a list of actions that can be performed depending on your role, the type of issue, its current status, etc.
In theory this meakes it easy to deal with an issue that's been assigned to you because only actions that make sense at this point are listed. However, as you're finding, a workflow that makes sense for a software bug may be awkward or confusing for a documentation issue. For example, I got some feedback that was initially classed as an Issue and none of the listed workflow actions looked appropriate to me. It turned out that this request would have been better as a Task or perhaps some new doc-related category--then we could design a suitable workflow for it.
I believe doc issues are generally simpler to describe than software issues, so I want a tracking system that makes it very quick to log an issue, even if that means it doesn't collect a stack of additional information that maybe would be handy one day. As long as I understand what the issues are, I don't need to have them broken down into a dozen categories. I'm not going to produce stats and graphs on this stuff, even if the tracking system makes it very easy to do so.
Really, all I need to know is:
- Where is the problem/issue?
- What is the problem/issue?
- How can I contact the person who raised it if I need more info?
- What is the current status?
> Where the system breaks down is when someone enters
> issues like âGuide X needs to be completely rewritten.â
This is perfectly good feedback and well worth capturing. You just need to be able to categorise longer-term issues like these so they don't appear in someone's stats as a bug that's taking a very long time to fix. Perhaps it would be given a status of "Accepted, not yet scheduled".
BTW you get exactly this sort of issue on the software side too--e.g. "Scheduling algorithm needs to be completely rewritten."
> Or someone enters pages of documentation reviews/comments
> as an âissue.â
I would handle doc reviews separately, not in an issue tracking system.
To sum up, if I had the chance to design doc issue tracking procedures, I'd do the following:
- keep it very simple, so that there's minimal perceived overhead
- get reporters to focus on describing issues clearly, not on classifying them minutely
- have a separate system for doc reviews
ComponentOne Doc-To-Help 2009 is your all-in-one authoring and publishing
solution. Author in Doc-To-Help's XML-based editor, Microsoft Word or
HTML and publish to the Web, Help systems or printed manuals. http://www.doctohelp.com
Help & Manual 5: The complete help authoring tool for individual
authors and teams. Professional power, intuitive interface. Write
once, publish to 8 formats. Multi-user authoring and version control! http://www.helpandmanual.com/
---
You are currently subscribed to TECHWR-L as archive -at- web -dot- techwr-l -dot- com -dot-
