Your Ultimate Guide to Writing a QA Documentation

Testing your average software solution is a tiresome and elaborate task. Moreover, if you need a decent piece of code, there’s no way out of testing. Yet, you can make your life a little bit easier by creating a proper QA documentation. The documentation saves a ton of time by streamlining your testing processes. It’s, also, your go-to asset in case something goes off the rails with the project.

This article is the second part of Your Ultimate Guide to Writing Test Documents. In this eight-minute read, we go through 6 topics:

  1. Checklists
  2. The Reasons for Creating a Test Case
  3. How to Create the Test Case
  4. The Lifecycle of the Test Case
  5. Test Suits
  6. Typical Errors When Creating a Test Document

Now, let’s continue our deep dive into writing a QA documentation. In this article, we are going to discuss five more topics:

  1. Defect Reports
  2. The Lifecycle of a Defect Report
  3. Typical Errors When Creating a Defect Report
  4. Test Plans
  5. Test Progress Report

1. Defect Reports

A defect report is a roadmap for getting a bug-free software. In short, the report describes any unwanted issue with your solution. It sounds simple until you start documenting. Below you can see an example of a typical defect report.

Defect Report Example

Let’s go through every section of the defect report:

  1. The identifier is your unique value for recognizing a specific defect report in a sea of others.
  2. The summary is your laconic answer to three simple questions “What happened?”, “Where?” and “Under what circumstances?”.
  3. The description is where you show the bug in all the details. You should describe the actual and the expected results. Moreover, it’s a good idea to provide a link to your software requirements.
  4. Then, you write about the steps to reproduce (STR). Don’t miss a step or your report may end up in a trash folder. 🗑️
  5. In the reproducibility, you show if the bug appears every time you follow the STR.
  6. The severity shows how harmful the bug is to the project. Don’t exaggerate because if the developer notices, your report might end up the last in the queue.
  7. The priority shows the urgency, and it’s a logical addition to the severity section.
  8. The symptom is a short label to stack your defect report with the other similar reports.
  9. Also, you should be a good tester and describe workarounds if you know about any.
  10. The comments can include all the useful information for your developer.
  11. Finally, the attachments include the list of files added to the defect report.

At the end of the day, you will come up with a report like one below. This report is from Jira, one of the many wonderful project management tools.

Defect Report Screen Example

2. The Lifecycle of a Defect Report

Submitting is only the first step before fixing the bug once and for all. There’s a whole lifecycle.

Lifecycle of a Defect Report

You start by submitting your defect report. Next, your project team has an option of either assigning it to a developer or declining the report. If your defect report is not a total mess, your team will accept it. Then, the assigned developer can either start fixing the bug or try to decline your report again. Usually, it’s your tech lead who decides if there are enough reasons for declining. Moreover, the tech lead has the power to defer any defect report under the pretense it’s not relevant.

Congrats! You’ve forced the developer to fix the bug. What next? You have to double-check the bug fix and verify if all is good. If not, you have to start all over again and reopen the defect report. This bug-fixing battle can be a long one. You can, finally, close the defect report only after about a week or two after a proper bug fix.

This defect report lifecycle is definitely not set in stone, and it should reflect the needs of your project. Be smart!

3. Typical Errors When Creating a Defect Report

There are dozens of mistakes testers make in a defect report. Yet, only a couple of them are typical and persisting. Let’s go through the typical errors when creating a defect report:

   1. A short and inadequate summary.

   2. The summary and the description are pretty much the same.

defect report error #1

   3. The description has no expected result, no actual result, and no link to requirements. Nothing at all.

   4. A print screen has no issue highlighted. This way, the developers might as well play ‘Find Waldo’ with the issue.

   5. Describing imaginary defects.

defect report error #2

   6. Putting away your work for tomorrow, and the day after tomorrow, and …. you get the idea.

   7. Making grammar mistakes. This is the easiest way to get shot by a grammar nazi. 💥🔫

   8. Describing features as bugs because you know it’s the best way to get fired.

   9. Not knowing the technical requirements of the tested solution. This type of a tester is no better than this little dog-o below.

defect report error #3

   10. Missing out important information in your Steps to Reproduce. 🙊

4. Test Plans

Now you know all about defect reports and, hopefully, about test cases and test suits too. It’s time to give you the big picture of a QA documentation. It’s time to make a test plan.

Your test plan should be your guiding document. It should include your to-do-list, strategy, resources, schedule and much more.

Your average test plan should answer thirteen questions:

   1. What is the purpose of the software solution? Is there any?

   2. What features should you test? Don’t go on a testing frenzy and test everything.

   3. How does the testing process look like? What are the methodologies, approaches, technologies, tools and so on?

   4. What are the acceptance criteria of your customer or your target audience?

test plan question #1

   5. When should you start and finish testing?

   6. What are the criteria for stopping and continuing tests? Do you stop testing when you’re out of cookies? 🍪

   7. What development resources do you need? What OS, how many copies and with what license? Yes, you have to worry about all of this.

   8. What hardware and what experts do you need? Look for the best in class.

test plan question #2

   9. How much time and money does your project have for testing? Is it worthwhile?

   10. Is there a test schedule? Perhaps, you should consider cramming all your testing into one day before deployment.

   11. Are your roles and responsibilities well designated? Who’ll do the job, if your lead tester disappears?

test plan question #3

12. Are there any testing risks? Is it risk-free not to test at all? 🤔

   13. What are the metrics and QA documentation your using? Maybe, go Rambo and document nothing.

Finally, to bring all the questions into a perspective here’s your free test plan template.

5. Test Progress Report

This is the final part of your QA documentation. I promise to keep it short. 🙂

The test progress report is like a test plan but with the current progress data added for comparison. In short, the report is a great way to keep your hand on the pulse of a project. So, you must mention eight things in your test summary report and you’re off to a success.

Test Progress Report

So, that sums it up! Thanks for making it to the end, and I hope you find the second part of the article useful. Here’s your reward: the test progress report template. Use it wisely!

Keep in mind. DevCom has solid experience with software support and QA documentation. In case you need the following services, Contact Us.

For more articles related to QA documentation, you can read the first part of this article titled How to write test documents: why you need them, and how to get started.

Written by Romanyuk Oleg, Marketing Manager @ DevCom.