How to Write QA Documentation That Will Work?

At last your designers and a team of developers finish work on an excellent, compiling, and feature-rich website. Your clients are so excited! They are ready to make a payment to your company’s account. The last and only thing that should be done is testing the product before the final release. Yet, if someone thinks that it is a quick and simple process that can be neglected, I have some bad news for them…

Quality Assurance is a necessary step towards launching a successful software product. It is just a small part of all project work, but nobody says it is simple. There are so many types of software testing — automated and manual, exploratory and functional, compatibility, UI/UX, regression, unit, API, and performance testing. Good luck wrapping your head around all of them! 

What is common for all these types, however, is that each requires you to write a thorough QA software testing documentation. The quality of test documents defines whether your work will prove useful or go in vain. 

---

Types of QA Documentation

• Test Plan

A test plan is a document or a set of documents that describe all test activities within one project and outline all work carried out by a testing team or one tester. A test plan can include the following elements: the object of testing, work schedule and deadlines, criteria for the beginning and end of testing, strategy description, risks, and a list of tasks to be done.

• Test Design
  

A test design is the process of designing and creating test cases for further testing of software. Test design should always consider the specifications of a project as well as requirements.

• Test Case
  

A test case is a formal document that contains a detailed description of steps and actions that should be taken to test the functionality or one of its aspects. Test case strictly specifies criteria for the functionality to pass QA testing. Each company has its own rules for test case, but to some extent, these rules are similar everywhere.

• Use Case
  

A use case is also a document for testing a product or software, but it is less formal. Use case is used to predict certain use case scenarios and based on these scenarios, build strategies for testing a product. Use cases are often developed based on business objectives and critical test path validation.

• Defect Report
  

A defect report is a document or a case that describes the situation, the sequence of steps that led to an error on the tested software. Most often, defect or bug reports also include a description of the expected correct result for this particular sequence of steps.

• Checklist

A checklist is a document that contains a brief description of the functionality of the software for testers to check it. Creating and writing checklists usually goes instead of writing test cases since checklists speed up preparation for testing.

• Software Requirements Specification
  

The software requirements specification is a complete and detailed description of the software being developed. I can outline the following features of software requirements specification:

1. comprehensive description of the functionality of a product;
2. clarity of requirements;
3. absence of inaccuracies in the description;
4. simplicity of concepts described;
5. fairly clear detail.

But it’s still unclear for you how to write high-quality QA documentation? I write this article to make your life a bit easier. So here it is, your ultimate guide on how to write software QA documentation that will work.

Make a Test Plan and a Test Progress Report

The test plan and progress report are fundamental components of the quality organization of the testing process. They include all necessary and important information that describes the testing process. The creation of a test plan incomparably improves the quality of a product. It allows you to analyze whether all stages of testing flow successfully and effectively.

Before creating a QA plan document, ask yourself “What is the purpose of the software solution?” and “What features need to be tested?”. Do not rush into testing every single part of your software. You need to decide what methodologies, technologies, and tools will you use.

The test plan will help you understand the following: 

• What are the acceptance criteria?
• What resources do you need? What operating systems, how many copies, and with what license? Do you need any technical consultants?
• Are your roles and responsibilities well-designated?
• What are the testing timeframes?

The test progress report is another part of the QA documentation, which is similar to the test plan but with added data on the current progress. This document lets you and your development team monitor project progress and identify organizational issues if any.

Create Test Cases

Once you clarified the set of functions that need to be tested in your test plan, you need to create a test case for each part of your software. Test cases are pretty simple – this QA documentation consists of 7 sections: ID, Test Case, Testing Steps, Expected Result, Status, Actual Result, and Comments.

1. ID is a unique number assigned to your test case.

2. In the Test Case section, you point out the requirement you will be testing and provide a link to it in the specifications document.

3. In the Testing Steps section, you list all the actions needed to complete a test case.

4. In the Expected Result section, you summarize the outcome of a particular test if it is successful.

5. In the Status section, you indicate if a particular step passed or failed testing.

6. In the Actual Result section, you explain what was the outcome of a failed test.

7. The Comments section is not obligatory, but you can add it to leave some additional notes.

Write a Defect Report

The defect report is an important element of QA documentation, which registers any unwanted issue with your program. It is a crucial element of the project documentation, which navigates you towards getting a bug-free software solution. Sounds simple, right? Yes, but only until you start documenting. Here, you can see the example of a typical defect report:

The defect report consists of the following sections: identifier, summary, description, steps to reproduce, reproducibility, severity, priority, environment, and attachments.

1. Each particular software issue is assigned a unique number – the identifier. It optimizes navigation through QA documents and facilitates communication between developers, testers, and PMs.
2. In the summary section, you provide a concise answer to three simple questions: what happened, where, and under what circumstances. 
3. In the description section,  you describe the bug in all the details. You should tell about the actual results and the expected ones. It would be useful to provide a link to your software requirements.
4. Then, you write about the steps to reproduce (STR). It shows developers exactly how to reproduce the issue. Don’t miss a step or your report may return to you.
5. In the reproducibility section, you clarify if the bug appears every time you follow the STR. You should use numbers to show approximate chance e.g. 7 times out of 10.
6. In the severity section, you explain how much harm the bug may bring to the project. In other words, it shows the technological degree of influence of the defect on the entire system. Even a small issue may badly affect the entire application.
7. Priority shows how important a particular defect report is. Priority can be denoted with the help of letters – “A” for the most urgent and “Z” for the least urgent, numbers – “1” for the most urgent and “9” for the least urgent, or simply words like “high”, “medium”, or “low”.
8. In the environment section, you should define which operating systems or browser versions were affected.
9. Finally, the attachments include the list of videos, screenshots, or console logs files added to the defect report.

Keep These Useful Tips for Defect Report Writing in Mind

1. Write a sufficient and adequate summary. It does not matter if it is long or short. What matters is that it should be clear.
2. Have a look at the summary and the description. Do they look pretty much the same? You must have forgotten to outline expected and actual results in the description and to add the link to requirements.
3. Capture the issue with the help of a screenshot. It may save you and the development team a lot of time. Sometimes, one glance at the picture is just enough to understand the situation.
4. Before reporting the issue, try to reproduce it at least 3 times to be sure that it exists. 
5. Report the issue ASAP and notify your project manager or product owner if the issue is major. 
6. Take a look at grammar mistakes in your QA documentation for you not to be taken down by the grammar police. 
7. However comical it sounds, make sure that the issue is not a feature – review the documentation again!
8. Do not miss any important information in your Steps to Reproduce.

Submit a Defect Report

Defect reports go through a lifecycle – from the moment you report an issue to the moment the issue is closed.

The first step is to compile and submit the defect report. At this point, the Project Manager or a tech lead decides whether to assign it to a developer or to decline it on the ground of insufficiency or inadequacy. After the assigned developer has fixed the bug, you as a QA have to double-check and verify that it has been fixed. If yes, you can close the defect report. The best practice is to close it in a week or two. If the bug is not fixed, you reopen the defect report and send it back to the assigned developer. The bug-fixing process can be a long one, but you have to stay strong until all the defect reports are finally closed.

To Wrap Up

You simply cannot avoid software Quality Assurance services. Each airplane prior to the departure undergoes a technical check. If there is any issue, the aircraft is grounded until the problem is solved. Similarly, each software product needs to be checked before a launch. You cannot afford to deploy bugged software because users will not give your app a second chance.