Software Testing Documentation Guide (Why It’s Important)

In my Software Testing career, I have never heard people talking much about software testing documentation.

The general opinion about testing documentation is that anyone who has free time can do the documentation like a Test case, Test plan, status report, Bug report, project proposal, etc.

I myself won’t stress more about the documentation, but I can say it’s my habit to place all the data in black and white and to update others as well about that.

Software Testing Documentation Guide (Why It's Important)

Importance of Software Testing Documentation

My Experience

Just wanted to share my experience with you:

We have delivered a project (with an unknown issue in it) to one of our clients (angry client). The issue was found on the Client-side and it was a very bad situation for us. As usual, all the blame was on the QA’s.

The issue was something regarding the compatibility of one website. When it came to me, I was having proof that I didn’t get such a requirement document which stated that I have to check the compatibility of the website as well. Thank god I was safe.

That was a lesson for me, I realized the importance of documentation and from that day I started to work on documents and started creating test documents like Test plan, Test cases, sanity testing checklist, bug report and many.

“Ink is better than the best memory” – Chinese proverb

Test Documentation: What’s That?

We all read various articles on testing technologies and methods, but how many of us have seen articles on documentation? No doubt there are few, is it that documents are not important? No, but its’ because we have not yet realized the importance of documents.

But, if we observe then the fact is, projects that have all the documents have a high level of maturity.

Most of the companies do not give even a little importance to the documentation as much as they give to the software development process. If we search on the web then we can find various templates on how to create various types of documents. But how many of them are really used by organizations or individuals?

The fact is that careful documentation can save an organization’s time, effort and money.

While going for any type of certification, why is there a stress given on documentation, it’s just because it shows the importance of client and processes to individual and organization. Unless you are able to produce a document that is comfortable to the user no matter how good your product is, no one is going to accept it.

In my experience, we own one product, which is having a bit of confusing functionality.

When I started working on that I asked for some help documents from my manager and I got the answer “No, we don’t have any documents” Then I made an issue of that because as a QA I knew, no one can understand how to use the product without documents or training.

If the user is not satisfied, then how are we going to make money out of that product?

“Lack of documentation is becoming a problem for acceptance” – Wietse Venema

Even the same thing is applicable to User manuals. Take the example of Microsoft, they launch every product with proper documents, even for Office 2007 we have documents that are very explanatory and easy to understand for any user. That’s one of the reasons for which all their products are successful.

In small companies, we always hear “project rejects in propo sal or kickoff phase” it’s just because the proposal documentation lacks concise and expressive language, and to show the capability of the organization.

It’s not that small companies can’t deliver good quality projects but it’s their inability to express their capability. (I also work with a small organization of 80 employees, and I have heard this many times).

I personally feel Quality is the only department that can make it possible. We are the only department which can argue on this and can provide a successful future for our organizations.

Let’s organize all the discussions in a few points from a quality perspective:

  • Clarify quality objective and methods.
  • Ensure clarity about tasks and consistency of performance.
  • Ensure internal coordination in client work.
  • Provide feedback on preventive actions.
  • Provide feedback on your planning cycle.
  • Create objective evidence of your quality management system’s performance.

10 Tips to Help You Achieve Test Documentation Goals

In general, software testing documentation is “It can be done only by the person who has free time”.  We need to change this mindset, and only then we can leverage documentation power on our projects.

It’s not that we don’t know how to do the documentation right. We just don’t think it’s important.

Everyone must have standard templates for all kinds of documentation starting with Test strategy, Test Plan, Test cases, and Test data for the Bug report.

This is just to follow some standards (CMMI, ISO, etc.) but when it comes to the actual implementation, how many of these documents are really used by us? We just need to synchronize our quality process with documentation standards and another process in an organization.

The simplest way to follow all kinds of documentation is to involve a person in the project from the kick-off phase who understands the project dynamics, domain, objective, and technology. Who else is better than QA person for this (of course there are technical writers present to do this – but consider a general scenario of small companies where technical writers are not present).

To achieve this goal of testing and documentation, I feel we need to focus on some points as given below.

Here are the top 10 tips to help you achieve your test documentation goals:

#1) QA should involve in the very first phase of the project so that QA and Documentation work hand in hand.

#2) The process defined by QA should be followed by technical people, this helps to remove most of the defects at a very initial stage.

#3) Just creating and maintaining Software Testing Templates is not enough, force people to use them.

#4) Don’t just create and leave the document, Update as and when required.

#5) Change requirement is an important phase of the project, don’t forget to add them to the list.

#6) Use version control for everything. This will help you to manage and track your documents easily.

#7) Make defect remediation process easier by documenting all defects. Make sure to include a clear description of the defect, reproduce steps, affected area and details about the author while documenting any defect.

#8) Try to document what is required for you to understand your work and what you will need to produce to your stakeholders whenever required.

#9) Use the standard template for documentation, just like any excel sheet template or doc file template and stick to it for all your document needs.

#10) Share all project-related documents at a single location that is accessible to all team members for reference as well to update whenever required.

I am not saying that by applying the steps you will get sudden results. I know this change won’t happen in a day or two, but at least we can start so that these changes start happening slowly.

After all “the documentation needs documentation”.  Isn’t it?

There are hundreds of documents used in the software development and testing lifecycle.

Important Software Testing Documents

Enlisted below are a few important software testing documents that we need to use/maintain regularly:

  1. Test Plan
  2. Test Design and Test Case Specification
  3. Test Strategy
  4. Test Summary Reports
  5. Weekly Status Report
  6. User Documents / Manuals
  7. User Acceptance Report
  8. Risk Assessment
  9. Test Log
  10. Bug Reports
  11. Test Data
  12. Test Analysis

Software testers regularly need to refer to the following documents:

1) Software Requirement Specifications
2) Functional documents

Conclusion

Software Testing Documents always play an important role in the Project development/Testing phase. So always keep things documented whenever possible. Don’t rely on verbal communication. Always be on the safe side.

Documentation will not only save you but also help the organization in the long run by saving thousands of dollars on training and most importantly on fixing issues caused due to lack of development and testing documents.

Don’t document, just to avoid finger-pointing at you, the habit of documentation will certainly bring a systematic approach to your testing process, leaving the ad hoc testing behind.

About Author:  This article is written by STH team member Tejaswini. She is working as a QA manager in an organization.

What other documents do you maintain during your daily testing activities? Feel free to share your thoughts in the comments section below.

Recommended Reading

118 thoughts on “Software Testing Documentation Guide (Why It’s Important)”

  1. .i learnt some thing from ur experience and used to know importance of documentation. Recently I have started my testing carrer.keep posting like this articles.it was very helpful

    Reply
  2. Hi mam,
    i m working as a software tester in a com.can you pls tell me more about test plan ,test execution?
    i ‘ve got a new project in php.There is many field to add a user and patient.
    Shall i test each field to prepare the test plan?

    Reply
  3. Hi Tejaswini,
    It’s a great experience to read this article. I havn’t
    imagine that Test Doc. has so much importance.
    Your experience proved a saying that “If it’s not written down, it doesn’t exist”.Thanks a lot.

    Reply
  4. Hi Tejaswini,

    Good article many times our team faced this issue. I also faced the same issue in my project. But learnt to document all the things what I work at least in notepad. Will be waiting for 2nd article

    Reply
  5. @ Siddharth Shukla

    Thank you for sharing.

    still have a confusion on Defect/Bug, Failure/Error

    For Defect you have given the “unexpected result” For Bug “Deviation from the expected result” i think these two meaning are same right. can please give me some examples

    Reply
  6. Thank u for sharing Sidharth.
    Coud u please help me in the Question,

    How do u produce testing documents?
    What is the best answer for it.

    Reply
  7. Very Helpful Article…we surely make a practice of it and will surely inform my Software Testing Colleagues regarding this Article….:)

    Reply
  8. Nice work!
    You narrated very well about the importance of documentation. But, about the situtaion you had with your angry client, I don’t think that the proof of requirements document saved you (or QA team) from getting blamed. Almost every process oriented 0rganization maintains designing the requirements document. In your case, instead of searching through all the requirements documents, the best practice could be looking at Traceability Matrix document, through which you could easily identify if there is any such requirement from the customer and if so, have we addressed it or not.
    I also feel that, requirements document is not a work product of tester’s effort. However, tester can verify it for the correctness of same.
    As I said earlier, you did a great job on posting this article. I also agree that most of them in the team have an impression that the documentation is a free time work. To vanish this myth, tester should be more creative to prepare effective documentation. To derive effective scenarios they should speak to SMEs/BAs/Sr.Developers to understand the customers business process well. In our agile process, we use user stories in preparing test cases.

    Once again, thanks for sharing the info and keep up the good work.

    Best Regards,
    Asha

    Reply
  9. very nice article…and needed information for everyone who is looking forward to explore their carrier in testing field

    Reply
  10. hi everyone my name is sumanth iam looking for a job in testing field i have experience of 1.5 years please if u knw any… let me knw…
    thanking u

    mail id:sumanthpathi2016@gmail.com

    Reply
  11. hi everyone my name is sumanth iam looking for a job in testing field i have experience of 1.5 years please if u knw any… let me knw…
    thanking u

    mail id:sumanthpathi2016@gmail.com

    Reply
  12. can you please guide me how to create a test plan on client requirement doc

    Reply
  13. It is good and informative.

    Reply
  14. Very useful with key pints indeed a Good read.

    Reply
  15. great information on Software Testing Documentation Guide

    Reply

Leave a Comment