The ultimate guide to QA documentation

On planet Earth, software development is unimaginable without a QA (quality assurance) team.

In a department dedicated to software quality, QA employees certify that software is error-free and working as intended.

The development and QA teams collaborate closely and often employ similar tools and methods to guarantee success.

For example, just like software development is supported by software documentation, quality assurance is also supported by its documentation.

What is QA documentation

The role of quality assurance is to review software, therefore ensuring its quality.

The discipline employs testing to verify that software is free of bugs, functioning well, and overall pleasant to use.

This is a relatively large undertaking, so it’s imperative to employ an organized approach.

This is where the QA documentation comes in. A set of documents about every possible testing action, these reports are essential for coordinating your testing strategy.

They define the testing scope, detail execution processes, report defects, and more.

This topic was discussed on a Quora thread, with a user asking for an example of QA documentation:

Although not a standardized testing document, the answer summed up QA documentation well.

These documents list possible failure points, identify segments to test, and then outline the most effective testing strategy— like the above example. In sum, they’re a guide to software testing.

However, broadly speaking, there are three categories of QA documentation, shown below:

Test planning documents are comprehensive records describing the testing method, detailing the scope, resources, responsibilities, etc.

Another document variant is test specification records which outline exact testing parameters (e.g., input and output data, execution steps).

Lastly, there’s documentation to list your testing results and report bugs.

For maximum benefits, try hosting this QA documentation in a single shared location to make it accessible to employees.

If you’re unsure how, documentation tools like Confluence can help you.

Such tools provide a space to manage all of the documentation pertaining to your business in one place.

Here’s an example document:

This is a test case uploaded to Confluence. With such public records, employees will know which test cases have already been performed, helping them organize their tasks.

As such, Confluence is an excellent answer for QA documentation hosting, as it should significantly streamline collaboration while providing transparency.

Why is QA documentation important

It’s hard to imagine a QA team without QA documentation. These documents pertain to almost every testing activity imaginable and are often incorporated into QA processes.

They’re the crutch that testers rely on to do their work.

The importance of QA documentation is perhaps most easily illustrated with the following statistic:

30% of the workday is almost two and a half hours. Over a quarter of the workday is lost daily, just trying to find information.

However, QA documentation can help mitigate this issue.

Extensive documentation that covers bugs, testing approaches, testing plans, and more, ensures that QA professionals don’t flounder to find the data they need.

Instead, all the information is readily documented and available to all, automatically saving time and increasing the employees’ productivity.

In fact, such documentation likely saves the most time with new employees. This Quora user explained why:

By reading test cases and other QA documentation, newcomers can familiarize themselves with the software and standard testing practices. And, best of all, they can do so independently.

There’s no need for anyone to sit down for hours and walk them through company procedures. Instead, new hires can educate themselves via the documentation information.

Besides helping with knowledge sharing, the intelligence the documentation hosts is also invaluable financially.

The longer a bug remains in software, the more expensive it becomes to fix.

Consequently, it’s generally accepted that errors are best solved sooner rather than later. Research has also proven this, as the visual depicts:

Costs rise as the project advances. However, a quality testing record should specify the reason for the error and offer possible solutions, ensuring that the bug doesn’t slip into production.

As such, it’s imperative to record testing processes correctly and minimize later risks. QA documentation helps track all defects, helping your company keep costs down.

What are the types of QA documentation

QA practices include a vast scope of activities, including various software testing approaches, detecting software bugs, and requirements analysis.

Because of its variety, QA is supported by numerous types of QA documentation designed to facilitate these processes.

Here’s a brief overview of the essential QA documents:

All five types of documentation are a considerable help during software testing and defect resolution and are invaluable in most QA activities nowadays.

The following sections will detail each document type and illustrate why these texts are so essential for QA teams. 

Test plan

A test plan is arguably the most important and definitely the most comprehensive document in QA documentation.

This text is an extensive, detailed record that outlines the complete testing process, covering every possible aspect.

For example, a test plan will describe testing approaches, resources, responsibilities, tasks, work schedules, risk assessments, pass/fail criteria, bug definitions, and more.

To understand its huge scope better, here’s a sample table of contents:

As you can see, every aspect of the testing process is covered.

The test plan is ordinarily available to everyone involved in the project (including stakeholders), so the testing process is transparent to all.

Furthermore, this document can likely answer any questions anyone has.

Finally, it’s essential that the test plan is created before testing starts, as the document is essentially a testing guide.

The test plan serves as a benchmark throughout the entire testing process.

Checklist

A much more concise document than the test plan, a checklist is used during the testing process itself.

This document lists software functionalities and features that need to be tested, with an accompanying test status (i.e., the test result).

QA employees use the checklist as a reference point for what needs to be tested and systematically work their way through the document, updating statuses as they go.

Take a look at this checklist example:

The checklist is essentially an overview of what features have passed all tests, which have failed, and which remain to be tested. It’s a summary of the current work performed.

When updating the checklist, it’s helpful to color-code the results, as depicted above. This automatically improves the checklist’s readability.

As for preparation, checklists are created per the software requirements specifications. That way, every essential aspect is thoroughly tested.

Test case

Unlike a test plan, a test case is the most minute and small-scale QA document. It describes the most basic software testing component—the actual test itself.

A test case is a complete test outline that provides testing steps, test data, preconditions, the expected result, and more.

All this information should be highly detailed, as testers require it to perform the test correctly.

Here’s a sample test case:

These test cases function as a guide during testing, instructing testers how to conduct the testing.

For example, the expected result essentially constitutes the fail/pass criteria. If a tester encounters the expected result, the test passes. If not, the test fails.

It’s a good idea to allocate plenty of time to writing test cases, as a high number of those guarantees better coverage.

The more test cases at your disposal, the more thorough the testing.

Test scenario

If test cases are the most specific, detailed, and minute component of your testing approach, test scenarios are the next step up.

A test scenario breaks down software’s functionality into modules, grouping similar tasks and actions into one umbrella term.

In other words, a test scenario consists of related test cases. For example, a test scenario could be password reset.

That test scenario would then contain several test cases, such as password reset if an invalid email is entered, password reset with security questions, etc.

Here’s a real-life example of some test scenarios:

As you can see, each test scenario is allocated an ID and a priority indicator. That way, testers know precisely what scenario to clear first.

The number of test cases is also listed, so testers can gauge each scenario’s size and estimate how long it will take to test.

Bug report

Last but not least, a bug report differs from the previous documentation because it isn’t used to facilitate software testing. Instead, bug reports are created as a result of software testing.

When QA employees are testing software, they’ll uncover defects.

A bug report is a comprehensive record of this defect, containing all possible details developers need to solve the issue.

Here’s a sample bug report:

The bug report provides steps to reproduce the bug, its priority, screenshots, etc. With this document, developers are fully briefed on the issue.

Bug reporting can be a lengthy process, but bug reporting tools greatly facilitate the procedure.

For example, with Shake, just shake your mobile device, and a comprehensive bug report will automatically be sent to the developers.

Here’s a sample bug report:

The bug report contains everything developers will need: environment details, logs, screenshots and screen recordings, and more.

Who is responsible for QA documentation

We’ve established that QA documentation is hugely helpful for testers. However, who writes these documents? Who’s responsible for them?

Software testers typically create checklists, test cases, test scenarios, and bug reports. These texts are part of their day-to-day work, making them more than qualified to compose them.

After all, these documents are shorter, small-scale reports.

The test plan is another story. Because of its scope, length, and importance, writing the test plan is a collaborative effort with the following contributing parties:

As the most experienced and knowledgeable team member, the QA team lead normally writes most of the extensive test plan.

However, they should ask for input from their team members, e.g., regarding the schedule and roles.

Finally, once the test plan is completed, it’s submitted to the QA manager for review, who makes any changes they deem necessary.

In addition to the QA team, the test plan might also require insight from non-technical personnel.

This topic was discussed in a Reddit thread:

Business analysts and project managers should contribute as well.

For example, since the test plan is partly based on business requirements, they can help determine the acceptance criteria and what features to prioritize.

However, all of this is under the assumption that the company lacks a technical writer. Most smaller businesses do, so it’s not uncommon.

However, most larger organizations have a full-time writer on staff.

In such firms, it’s not unusual for the technical writer to collaborate with the QA team and compose the documentation together.

Kumar Raman, Documentation Lead, recounts a request from a project owner:

In this situation, there was a dedicated department handling solely documentation.

If a business is large enough to support that, technical writers will then work closely with QA to compose QA documentation.

Conclusion

QA documentation details almost everything concerning your employees’ testing efforts, regardless of whether it happens before, during or after the testing itself.

The test plan, for example, is a great starting point for anyone involved in the project.

On the other hand, bug reports are the results of extensive testing and what developers need to correct defects.

Finally, checklists, test cases, and test scenarios are resources testers need to make their own testing processes smoother.

By using these documents, you can break down information silos, empower new employees, organize your QA processes, and more.

Nowadays, QA documentation is so prevalent it’s hard to imagine QA teams without it.