Bug reporting on documents

Question

In my job I have to test Markdown documents. This includes looking for bugs related to:

• The procedure described in the document
• Typos, grammar mistakes, etc.
• The HTML version of the document

Right now, what we do to log bugs is this:

1. If a bug is a found, I write a comment in the document. I don't like this because:
   • It is not clear where the bug is (is the bug in the word or paragraph that is before or after the comment?)
   • I can actually break the document if I don't write the comment correctly (e.g. by forgetting the closing -->)

2. Once I am done testing, I use a tool that looks for the comments I wrote, and I paste them into a new issue in our bugtracker. I don't like this because:

   • Instead of creating a new issue per bug, I create one issue per document. This makes it hard for me to keep track of what bugs were fixed and what bugs were not fixed.

   • It may be hard for the devs to understand the bugs (imagine reading something like this:

     Line 8: SEVERITY 3 - PROCEDURE - Consider rewriting the above paragraph for clarity

     Is it immediately clear what the bug is? The dev now has to open the file that I edited and look for each and every one of the bugs. How tedious is that?

3. In order to get statistics about the bugs found (type, severity, etc.), we use another tool that creates an Excel spreadsheet, and from there I have to create the graphs of statistics. I don't like this because:

   • We have to use two tools,
   • I have to create the graphs manually.

This whole procedure is too complicated and hinders my performance.

I know I can fix (2) and (3) by combining both tools into one, and automating the creation of graphs.

But how can I fix (1)?

NOTE: this question is also applicable to other types of documents (MS Word, most importantly). Feel free to suggest ways of reporting bugs in these formats.

Answer 1

As @vincebowdren says, start with screenshots. There are numerous simple screenshot tools (I've been using the Windows 7 snipping tool for some time now - I can use the mouse to draw a rough circle around a problem area or highlight something), many of them freeware. I'd recommend mapping a keyboard shortcut to start the screenshot tool, for speed.

You don't say if you're reporting a single issue per document in the bug tracking tool because that's what's required or because that's how it's always been done. If you move to one bug per issue you'll make reporting a whole lot easier (your tool is guaranteed to have a database back-end, which means you can build a simple front end to generate your graphs automatically - there will be an initial time investment to build the reporting interface, but once done it will save a great deal in time and accuracy)

If reporting a single issue per document is policy and you can't change it, I'd recommend these options:

• Number the listed items and link it with a screenshot. This will give you an easy way to tell whether the fixes are covered, and the developers an easy way to know what the problem is. If your bug tool doesn't allow you to include screenshots inline, place the files in a shared directory and list a link to them (for example): #3: Line 8: SEVERITY 3 - PROCEDURE - Consider rewriting the paragraph in \\files\issuefiles\documentname\item3unclearpara.gif for clarity.
• Use Excel's ability to generate charts to build your graphs if you can't combine the tools. You may need to transform the data that's generated automatically, but that's doable through macros.

If you can change to reporting one issue per issue, I'd suggest considering these procedures:

• Include the document title/name in each issue created for that document. I'd do this even if your issue tracking tool allows you to create a parent/child relationship between issues. It means you can easily search the issue tracking system for all issues relating to a specific document.

• If your issue tracking system allows parent/child relationships, I'd suggest creating a master issue for the document, then link every individual issue to it as a child issue. This can be used to simplify tracking and reporting.

• With an issue per problem found, you can directly mine the issue tracking database to generate metrics and graphs. Until you can get this built, using Excel's graphing capability should be doable.

• Include a screenshot with each issue by whatever method is best supported by the issue tracking tool. Annotate or modify the screenshot as needed.

Free screenshot tools I know of:

• The Windows 7 and above snipping tool is basic but functional. It doesn't support text annotations

• Jing provides a good free screenshot tool which supports text annotation.

• The Print Screen key and pasting into Windows Paint or similar can do basic image annotation and markup

• More information on screen capture tools can be found here: http://www.techsupportalert.com/best-free-screen-capture-utility.htm

Answer 2

Screenshots. Take a screenshot of the document, edit the image to highlight the problem area, and add it as an attachment to your bug report along with the markdown document (unedited).

Answer 3

I would suggest you to use following tool:

Ducklink Screen Capture. http://www.ducklink.com/

You'll find it very useful as it provides the friendly capture and editor.