How to write a good incident description/file a clear bug report

Issues are an important way of organizing tasks around both development and maintenance of the application as well as for collecting collective knowledge about the application and the use of the technology. To efficiently share the knowledge and transfer tasks between developers and other parties involved, it is important to create issues in a way that makes them complete yet concise.

I have been working on a fearsome number of issues lately.
I encountered some very well written incident reports that made it very easy quickly reproduce the problem and start working on the resolution. However some of them were very vague and required me to do a lot of interpretation, guesswork and foul mouthing before I even understood what the problem was and how to reproduce it. The latter clearly is not the most efficient way of going about it. So I tried to write down what I think should be in the ideal Incident description. Below follows my first attempt at an ‘Incident description instruction’. If you have suggestions for further improving this instruction, please write a comment on this article!

When you create an issue, please make sure that it has the following elements, in this order:

1. What is the behavior you are seeing (note: this could be a screenshot)
2. What is the behavior you expected (why is what you are seeing not OK
3. What are the steps to take in order to reproduce the issue
4. What are the artefacts you know or suspect to contain the issue (VM file, JSPX files, JS or CSS,….)
5. Optional: Additional information such as Error messages, Stacktrace, Screenshots, excerpt from logfiles, JavaScript console messages etc.
6. Optional: Workaround – is there a way (temporarily) avoid/work around the issue? (if so, what is it?)
7. Optional: your ideas about what has brought the issue about (for example if the issue started occurring after a certain event – what was the event? If it only occurs under certain conditions: what are the conditions? If you have an idea about cause and/or possible remedy – please write it down

Tracking the Issue Resolution

When solving an issue, it is equally important to write down your analysis and resolution in adequate detail. And it is important that you not start writing issue comments only after you completed its resolution, but write as you work – as a log.

However, first judge whether the issue is specified in enough detail for you – or your colleague! – to start working on it, otherwise immediately return it to the initial logger with an indication of why it is not a proper issue description.

When you accept the issue, confirm that you can reproduce the issue; see whether you can describe it in more general terms if the issue is more generic than the initial report suggests.

If the analysis yields insights – and hopefully it does – write them down. Describe how you performed the analysis if this was non-trivial: log-files you inspected, trials you performed (if you do this and this, or that and that….), etc.

If you used external resources – internet, documentation, forums – to learn more about the issue and perhaps possible solutions: mention them in the issue comments.

If you considered several solutions to the issue and picked one – mention them all, and motivate your choice. (perhaps the solution turns out not be adequate and you may have try an alternative)

Describe how the solution you apply will fix the issue – if non-trivial (do not write how removing a quote will help the page to compile properly). And how it is applied – high level: where do you have make changes.

Finally: describe that (and perhaps how) you verified that the issue was fixed. Check in the changed sources and include the Issue Reference (we use Subversion and Jira and from the issue reference in the Subversion check in notes, Jira can create a list of all artefacts that were changed and checked in to solve the issue) in the Check In notes. Only when the check in is successful should you mark the issue as resolved.