2.20. Clarity, Pertinence, and Action

One of my clients refers to long test documents as "shelfware." He has seen too many test managers and senior test engineers spend too much of their time filling enormous binders that then sit on shelves, untouched during test execution. My client's comments are a cautionary tale: veer off into a morass of documentation for its own sake— just to follow a standard or to "fill in the blanks"—and you can lose focus, relevance, and credibility.

The style of writing matters, too. Avoid passive verbs. Don't say that something "is to be done"; instead, say exactly who is to do what and when. Defining roles and responsibilities keeps you out of the trap I saw one client's test manager fall into when she wrote a test plan that was just a collection of statements of principle and pieties. ("Testing is good," "Bugs are bad," etc.) Keep jargon, buzzwords, and so forth limited to those appropriate for the audience, and use a Definitions section to promote further clarity.

I keep my test documents practical, focused, and short, and they work well for me. This approach to planning, customized to fit your particular needs, will help you write effective test plans that you can really use.

Get Managing the Testing Process: Practical Tools and Techniques for Managing Hardware and Software Testing now with the O’Reilly learning platform.

O’Reilly members experience live online training, plus books, videos, and digital content from nearly 200 publishers.