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:
- 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
-->
)
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?
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.