As far as I know, there isn’t yet a support group for testers. But if there were, I believe many of us would confess to having a severe aversion to writing test documents.
Part of my job definition is to be the annoying person who pushes people to write documents. I defined the document templates, and I review most of the test documents my team produces. I can tell you that it’s just about as you imagine: unexciting and much less fun that running tests and finding an interesting bug.
Worse, because I am the one preaching about test documents, I have to be a good example and do what I ask others to do. I can’t skip writing test documents for any of the projects I am responsible for, even though I really don’t enjoy it. In fact, when writing test documents, I have to get up every now and them and take a walk in the hallway just to wake up.
Even though it’s not the most interesting task, writing test documents is a good practice to have. It enforces an orderly thought process about the test challenge ahead, explains what we’re planning and why we do things this way and not another way, and improves the action plan, the test strategy, effort estimation, and task partition.
Documented plans also let stakeholders know what they can expect to get from the validation team. It allows feedback if we made mistakes in our plan and reduces the number of surprises caused by misunderstanding or mismatched expectations.
None of this should be news to you, but it still doesn’t make the process any more fun. However, I may be able to make the idea of test documentation a little easier, or at least a little more palatable. You’re going to have to do it anyway, so why not try to overcome your hatred of test documentation and try to get in a better mental state about it? Here are five tips.
1. Write the test document for yourself
Get used to the fact that very few, if any, people will read the test document. This is OK. The main beneficiary of a written test document is the author. Writing it helps you order your thoughts and organize the test plan into clear steps you (and anyone else) can understand.
Besides, if you don’t expect anyone to read the document, you won’t be disappointed when that’s just what happens. In their book Exploring Requirements: Quality Before Design, Donald C. Gauss and Gerald Weinberg relate to this disappointment. They write, “The document is nothing; the documenting is everything.”
Writing the document is the goal. If it is read by others, that’s a bonus.
2. Use your human thought process
In today’s Twitter world, we feel that any idea can be conveyed in one or two sentences—and if we need more, someone must have already found a trick or developed an app that will do the job for us. We believe that if we only think hard enough, we will find a technological solution that will write documentation for us, like Doxygen did for code documentation.
It’s frustrating to spend a lot of time doing something manually when all the time you feel it could be automated and be done more efficiently. But writing a document is a thought activity, and luckily no one yet has found out how to automate that. So stop torturing yourself about wasting time and revel in the fact that this is a human job that isn’t replaceable.