Sunday, 8 March 2015

The Basics - How To Document A Bug

An occasional series looking at best practice for common documentation tasks and situations.

Documenting a bug is a common activity for technical writers who work in production environments.  Although every company will have differing standards for documenting bugs, there are key pieces of information that should be transmitted to the customers (internal or external), regardless of your company's preferred style or terminology.

These key pieces of information are:

  • Who reported the bug?
  • What was happening before?
  • Where was it happening?
  • When was this happening?
  • Why was this wrong?
  • What's happening now?

Let's look at these items and explain why they are so important.

Who reported the bug?

Each customer will want to know whether the bugs they have reported have been fixed.  That's not to say that they won't be interested in others bugs that have been fixed, but their priority when reviewing your documentation will be to find out if the things that they think need to be fixed have indeed been fixed.  To track customer reports of bugs, most companies will use some type of ticket system.  Each call to the support desk will be assigned a ticket, and if after investigation it transpires that there is indeed a bug in the system, the development team will add a work item or task to their backlog to fix it. In agile environments these tasks will be completed in priority order; this means that a bug may not be fixed in the next release that goes out.  Therefore the ticket number that the customer has been given should be visible in the title or heading for the bug when you document it.  This will allow the customer to easily search for the bugs that they have raised with the support desk***.

What was happening before?

It's easy to say "The doohicky process is now working correctly." - and this will be an accurate reflection of reality - but that doesn't really help the customers very much.  If the reader doesn't know what the process was doing before it was fixed, they won't be able to perform their own user acceptance testing on the process to make sure that it is now working correctly (bear in mind that "correctly" may be a matter of opinion that customers don't always agree on).  It's also important that customers can check to make sure that an incorrect process hasn't amended their data; without knowing what the problem was before, their analysis will take much longer.

Where was it happening?

Not so much a problem in an app with 1 screen, but in any large application it is important to give the customer the default menu path to the location of the problem.  For example, Form A > Tab B > Grid C > Column D.  Customers want to be able to easily reproduce the conditions in which the bug was occurring, and in large systems you should tell them exactly how to get there to save them time and confusion.  It also allows them to disregard the bug fix if they don't use that part of the software.


When was it happening?

This doesn't mean "we found it last Thursday but it's been happening since the last release", which is something a developer once told me when I asked him this question. Rather, it means "at what point in the user experience did this bug occur?".  As with the Where, the When helps customers quickly reproduce the conditions in which the bug was occurring so they can test the fix. 

Why was this wrong?

For some bugs, such as the application crashing, this question is superfluous.  But where a calculation is performed incorrectly, or a process sends data to the wrong place, it might not be obvious to a person reading the documentation why this is a problem. For example, "The doohickey process was only storing data to the current and historical tables." might be an accurate explanation of the problem, but doesn't give any indication of what table(s) the process should have been storing data to.  A more complete explanation would be "The doohickey process was correctly storing data to the current and historical tables, but was not storing data to the audit table as per the specified requirement." 

What's happening now?

All of the above questions combine to form the description of the problem.  This question forms the description of the solution.  If you have entered all of the relevant information in the problem section of your documentation, the solution should be fairly simple: one or two lines stating that the problem will no longer occur (e.g. "When Save is clicked data will now be stored to all of the correct tables.") or an explanation of the change in functionality (e.g. "When the doohickey process runs, it will now include [variable x] when performing the tax calculation.").

All of this can be boiled down to: Who, What, When, Where, Why, Now, or as a mnemonic, W5N.  If you can remember to use W5N when documenting a bug, you'll always provide most if not all of the information that your customers need to see.

*** - If the bug was found internally, or doesn't have a ticket number assigned to it for any reason, either the bug is documented without a ticket number, or depending on your company's procedures, may not be documented in externally facing documentation at all (on the basis that some company's don't feel the need to tell customers about bugs that the customers didn't know about).