Using an issue tracker for documentation updates?

Question

We use an issue tracker to track software issues: bugs, new features, enhancements, etc. Very often, the code change to resolve an issue requires an update to documentation; e.g. user manual, install manual, test procedure, etc. Generally the documentation is done by a different group of people -- tech writers, QA team -- but it is helpful for the implementer to give a brief synopsis of the required change when resolving the issue as fixed.

I'd like a lightweight method to encourage this workflow and I figure it can be done in the issue tracker. I can think of a few options to do this:

1. When the developer resolves the bug, clone as new bug against a "documentation" component summarizing the doc change required.

2. Add a "documentation pending" state to the workflow between "resolved" and "closed".

3. Add a custom boolean field to the issues, e.g. a "documentation update required" flag.

4. Add a custom text field to the issues that contains the proposed update summary.

There are pros and cons to each option; e.g. #1 will result in a lot of issue creation, where really the documentation update is just one more step in the workflow (#2). On the other hand, not all issues will have a doc update and need to go through the workflow.

What method have you found effective to track these documentation updates?

Answer 1

I would enter a new change request for the documentation that specifies what needs to be updated, and link it to the original change request. That allows the documentation group to have a clear view of what they need to do and it avoids tangling the workflow of the two groups unnecessarily. We also split requests that have multiple changes into a parent with multiple children to allow us to spread the assignments out better. This also helps our test group, because the get a steady stream of small changes instead having a huge load of changes dumped on them when a big change comes down the pipe.

Answer 2

Add a flag to your issues that specifies that a documentation update is required. Give your technical writers access to your issue tracking system so that they can see all of the issues that have been flagged. If they don't understand what needs to be updated in the documentation from the notes provided in a flagged issue, they can come talk to the person responsible for resolving the issue.

This is a process change that you would need to make everyone using the issue tracking system aware of so that it is done properly.

Answer 3

I think your custom field methods should work fine fine but we tend to use Sub Issues as a way to run our documentation workflow. Essentially it goes like this for us,

1. When a developer works on an issue and determines that new documentation needs to be written for the issue or existing documentation needs to be updated (or is even unsure), he fixes the core issue and creates a sub-issue linked to the current issue to complete documentation, with relevant instructions and assigns it to somebody doing documentation.

2. The person responsible for documentation resolves the sub-issue and notifies the parent issue assignee that he is done.

3. The developer or PM verifies that everything is fine and resolves the main issue finally.

Obviously, this is just another way of doing things and there are many pros and cons. Previously, we just used to let the developer implement the issue, comment on it (saying "i've fixed it like this...", re-assign it to a writer saying "documentation needed.." comment, writer would update docs and close issue.