How Much Documentation Is Enough for Your Project: The QA Perspective

Every project – be it IT or any other field – requires some planning and documentation. How much product planning and documentation you will require depends on the project’s type and scope.

A good and comprehensive documentation doesn’t sound like a bad idea, but does the old adage “measure twice and cut once” is right for your project? Or is the agile way the right way to go?

Agile vs.waterfall

Should you choose agile or waterfall? Well, it all depends, and the answer isn’t always that simple. The old-fashioned way was the waterfall way. You’d gather requirements, create the documentation according to those requirements, and then there would be a coding phase followed by a testing phase. A picture like this might be a good illustration:

The waterfall approach has both pros and cons. Its biggest disadvantage is that any potential issues or misconceptions discovered after the coding phase have already been implemented, so you will have wasted time and money on something wrong or obsolete. What if the customer doesn’t like the end result? The design might have looked great on paper, but once you’ve implemented it, it stopped looking so great.

On the other hand, very often, the agile approach has very little documentation and planning is limited to few next iterations, which also has some disadvantages. First of all, since there are no reference documents, the client must be involved at all stages of the software development process. On top of that, changing the concept of how it all should work might require periodic refactoring in order to maintain high quality.

Is Agile always better?

If the client has some time to take active part in the development process shouldn’t agile be better in every case?

The answer is ‘no’. In my opinion, it all depends on what the consequences of failure will be. The greater the risk of failure the more the waterfall approach will suit the project.

If you’re about to create a mobile quiz game or a dating app, going full-on waterfall won’t be the most efficient approach. Some planning designs and concepts will be required for such apps, but spending a month drawing exact button placements on the board and every single screen mockup will be an overkill.

On the other hand, all industries where you can cause a lot of damage by even a minor mistake are very good examples of where the waterfall approach might shine. Imagine the level of stability and the number of bugs allowed in plane-controlling software, a missile guidance system, or a system for a nuclear power station. Since everything has to be well-thought in advance and thought over twice before starting the development, “measure twice and cut once” it is the best allocation of the team resources. The consequences of failure will be of grave significance not only to the company responsible for the product, but for the average Joe as well. Consequently, there are only very few advantages of being agile for such applications, because the risk is just too high.

Waterfall might be handy in some situations

I have personal experience in working as a Quality Assurance Engineer with applications developed using both agile and waterfall methodologies. My waterfall experience involved software for hospitals and medical laboratories. From the QA perspective, the difference between working on projects in medical industry and working in the agile methodology in Netguru in agile methodology are two completely different things. In the medical industry, there was a requirement for every button and every feature to be described and analysed for all possible user scenarios. Testing a new small feature could take anywhere between three hours to a couple of weeks. For every feature or bug fix, I had to write an extensive test case that had to be checked by the test lead and then by super testers in order to be approved as a valid testing scenario. More often than not, the execution of test cases had to be recorded and then uploaded to the server as a proof that testing has been conducted properly. If a requirement was not clear enough or could be interpreted ambiguously, we needed to e-mail or call the functional architect responsible to clarify the issue. Sometimes it took up to a month to get an answer. I had spent more time on analysing requirements, creating test cases, and documenting my work than on actual testing.

Is waterfall worth it?

The waterfall approach might seem as overkill, but which one of us would like to get a wrong diagnosis from a doctor because of a software glitch. The potential consequences of an error in medicine might be disastrous, hence the heavy regulations and a slow but thorough process.

That said, this is the way only a few regulated industries have to go through, so how much documentation will be enough in a “normal” commercial project?

I can answer this question from my own experience: it all depends on the client’s involvement in all phases of the project. If a product owner has been designated and they are eager to answer all questions and be the project’s oracle, you won’t have to generate a lot of documentation. Visual mockups created by a designer and comprehensively described tickets will be sufficient. In the case that the communication between the team and the person responsible for the project is limited, you might need more documentation.

The agile methodology allows for more efficient time allocation than it is the case with waterfall. As a QA specialist, in agile, I do not need to document my work, but this requires trust between the client and the team, because there is no evidence of the ticket being tested. By not generating loads of documentation, I can spend way more time on exploratory testing and thus find more bugs and executing more complex scenarios.

Is agile more cost effective?

For most applications, the agile approach is definitely more economical in the long run. Since nothing can be fully tested and bug free, a thorough analysis, designs, and testing can never guarantee software entirely devoid of bugs. It’s way easier to change directions and be responsive in the constantly changing application market. If your QA has the option of clarifying all the ambiguities that ensue on a daily basis, going agile will have more business sense. Just remember to forgive your QA specialists for asking countless questions and creating a lot of Jira tickets to be evaluated – QA specialists are nit-picking by definition.