Documentation and The Tester

Over my years in the software business I have come to realize that the task of creating documentation for software is more than just a parallel activity to testing it. The two tasks have some interesting similarities, and if we can take advantage of it there is real opportunity for synergy.

The Development Perspective

Consider that Doc and Test both generally work from a Development spec. This document is written from the developers perspective – how they will implement these features that marketing requested. The problem is that this document often shifts the perspective away from using a tool toward breaking down its features – the deconstructed tool, if you will. Both Doc and Test need these details. But good testing and good documentation should come from a usage perspective. Both groups need to figure out how this information, and this feature, fit in the context of using the software, so they know how to describe it, and the logical usage scenarios to exercise it. (A marketing requirements doc might be of help.)

Synergies

Where is the synergy? The tasks are often coincident, but depending on scheduling one group might be ahead of the other. Share what you’ve got! A test plan or a set of test scenarios might be a great boon to a writer’s understanding of usage flow. And early draft documentation can help get a tester on the right track.

Sharing

What else can be shared? Maybe one has spent some time with the developer, and can pass on the brain dump. Are there any special setup instructions? This might be especially important for a new tool or a preproduction system. How about test data, or data generation scripts?

Strategy Sessions

Perhaps a strategy session can prove useful. I recall discussions on whether a new mode to an existing feature should be described in the section with the other existing modes, or whether it merited its own separate topic. The conclusion affected whether we would add incremental tests, or entire new scenarios.

Technical Writers

Technical writers tend to be pretty hands on, so they may well be the first to run the new code outside of the developer. Not surprisingly, they frequently find bugs. And not just early failures. In my experience writers seem particularly adept at catching consistency and interaction issues – probably because they often have a high-level perspective, wondering how the new feature can fit into the existing documentation, or how to structure a new document.

I have had the good fortune to work with some excellent technical writers. And they have had some darn good testing skills. In fact, I know several who have done tours in both roles. It can be a good thing to broaden your horizons.

Author Profile – Sean Morley

Sean Morley is a Principle Quality Engineer for Dassault Systemes. Having worked in a variety of roles on software tools for electronic design and test, he is currently focused on the testing of engineering software. Sean participates in test related forums and blogs at www.testyengineer.com in a concerted effort to improve his knowledge of the field and share his experiences. He appreciates all feedback, recommendations, and challenges as opportunities for growth, and can be contacted at seansync@gmail.com.