Thursday, June 17, 2010

Documenting the easy way

I recently read Michael Bolton's blog post on Test ideas for documentation and was inspired. I thought about the points he made and the questions he asked and figured I could use them in my own way in a project I'm currently involved in. I had this in mind when I read a blog post by Pradeep Soundararajan on his experiences from a recent project. That blog post is a great example of good story telling that really points out some important observations and conclusions we could all learn from.

The thing that caught my attention and instantly gave me an idea was the use of video test cases. It's a brilliant idea in all its simplicity. It's fast to do and easy to understand. Having just read Michael Bolton's text on documentation I immediately thought of using video for documentation. Not for documentation of test sessions but for the systems documentation that we are required to supply to our customer according to their holy process. The customer is an organization that relies on process and documentation and very little on people. It's the kind of place where some people still believe that a good process can be implemented that will solve all the problems caused be human error. They like best practices and that kind of stuff. You have probably seen this yourselves more than once.

Being in this environment it gave me great pleasure to introduce the idea of more video as part of systems documentation and of course as part of systems test documentation. I was ready to argue my case but I obviously managed to present the idea well enough right of the bat because the idea was embraced fully right away. I was a bit disappointed that there were no arguments since I always enjoy the argumentation part. More than once have I seen new ideas, and better ideas come to life as the result of good arguing by intelligent people.

The way I will use video is by making fairly short videos, screen capture, for each of the various application in the system and then simply naming them in a way that relates them to the relevant design specification document. By storing these together, and supplying a very brief document describing the naming convention and the relationships between the specifications and the videos. I will be able to produce this documentation at the same time that I am testing the system and virtually to two tasks simultaneously. There will be some work left to finish the job but the amount of time this will take is very small. I will use video capture to assist myself while testing as well as I use my notebook and OneNote to keep track of my testing sessions. I feel very good about the setup and feel very good about not having to write long, useless descriptions that are totally pointless and basically just a copy of the design specifications and that will never be read by anyone!

Many thanks to Michael Bolton and to Pradeep Soundararajan for providing the inspiration to think more about the subject and for the inspiration.


  1. You saw an idea and made it your own. That is the way to go Ola.

  2. Thank you Pradeep.

    This was one of the easy ones. I try to pick up ideas everywhere and the timing of my current project, Michael Boltons post and your post just clicked. A no-brainer really. Just pick it up and run with it!