Good Writing Leads to Good Testing

As software test professionals, you're well aware that terms like "quality" and "good" are often considered loaded weapons in our industry. So it's important to explain now what I mean by "quality writing."

What Is Quality Writing?
Quality writing is clear, concise, well-thought-out, and grammatically and syntactically correct. It conveys the author's thoughts to the intended audience without additional, unnecessary information. When someone reads a document that has been written well, he or she is able to quickly and easily ascertain the author's purpose for writing the document and what key points or issues the author covered.

There are two important elements in quality writing-the way it is written and what is written. The first section of this article covers the process, or "way," of writing. The second section discusses the "what" of writing. There are particular benefits from each element on its own, but your writing will be most effective if you pay attention to both.

Benefits of the Writing Process
Even the simplest forms of writing can prove invaluable in the testing process. If you're beginning a test effort, take any documentation you may be lucky enough to receive from the development team and re-write the key points in your own words. If you're able to transform a requirements document into a hand-written, bulleted list of items, you have a pretty good understanding of what the system is supposed to do. This type of list also helps you understand your particular role within the test effort since it allows you to see the features you are responsible for and the ways in which they interact with the rest of the system.

People cannot write well about things they are unsure of or do not understand. Therefore, if you find yourself unable to "translate" a requirement or feature, the developer may be fuzzy on the issue as well. This kind of inability to write about an area of the system under test should raise an immediate red flag. If you don't understand it, how can you test it? And if the developer is unclear about it, you've just found a potential nest of bugs.

Even if you don't receive any documentation on the system you're testing, coming up with a list of key requirements or features on your own can be extremely helpful. By writing the details of the system, you can come up with a quick overview of the system's functionality. You can also quickly realize where there may be "holes" in the scope of your test coverage. Whether you use a formally documented test plan with detailed test case steps or take more of an exploratory approach to testing, the benefits are the same. By writing your test plans, formally or informally, and comparing them to the overview of the system, you can see where additional coverage is needed.

The process of writing your test plan can reveal other types of "holes"-those in the system itself. You are more likely to catch problem areas early, which may warrant further development efforts, as well as areas that simply need clarification in the documentation.

These holes may appear immediately while you're writing your plan, but they often are much more apparent after the writing is complete. Give yourself a day or two away from what you've written, and when you re-read it, anything that doesn't fit or is missing will jump out at you.

The effort of writing your test plan will often foster increased interpersonal communication as well. Whether you're clarifying an item in the system's documentation or you're asking for suggestions on test data, chances are you will need to gather information from other people while you are writing. And any effort that increases communication between members of a test team or between the test and development teams is a worthwhile effort.

Writing can even help improve the way you communicate with others. Writing often must be tailored to a specific audience. In my case, I use a different writing style when I'm communicating with management, with fellow testers, and with software engineers. By practicing my skills at writing for different audiences, I'm also developing my ability to communicate orally with those different audiences.

Finally, being an effective writer can open a number of doors for career development. You could write a white paper for one of your company's products, prepare a speech for a local special interest group, create a presentation to share with other members of your team, or even present your experiences at a national professional conference. In any case, your ability to write well will provide new opportunities for you, both individually and within your company.

Benefits of Written Artifacts
While the process of writing can be helpful to your testing efforts, the results of those efforts provide unique benefits of their own. Again, not all test groups produce the same types of documents, and the terms "test plan" and "test case" mean vastly different things to different people. In any case, any written documents you produce as part of your test efforts will provide some, if not all, of the following benefits.

Documents serve as useful artifacts that can be shared with other departments within your company, with regulatory agencies, with test partners, and with any other interested parties. If written well, your documents will provide these third parties with the information they need. That way, you can spend your time testing rather than answering questions about poorly written documents. You also establish yourself as a reliable source of information, which will be good for your career. If, however, your writing is sloppy or incomplete, chances are you'll spend more time clarifying what you "meant to say" than you did writing in the first place. You will be perceived as disorganized or as a muddled thinker, which will not be good for your career.

At times, testers prepare documents in order to actively solicit questions and comments. Another benefit of a well-written document is that it can be distributed long before other people's responses are needed. That way, your audience has sufficient time to review your work, come up with their own list of items for clarification, and present their questions to you in a helpful fashion. Without a written document to distribute in advance, the responses from your audience will be "on the spot" and may not be as comprehensive as you would prefer.

The writings of one test team member can also serve as models or guides for others. Chances are that not every member on the test team will have the same level of skill or comfort with writing. In those cases, the well-written works of some members make good examples for the rest of the group to study when developing their own writing skills. While templates carry potential problems of their own (see the Pitfalls section below), when used appropriately as a guide they are an excellent way to help others improve skills by example.

Your writing can also benefit the entire test team by providing a single, professional "look and feel" for the group. By using the same well-prepared document outlines or "shells," each member of the test team can write in his or her own personal style while maintaining the written "image" of the group. Of course, the quality of the writing that "fills in" the outline must be high, or else the image is quickly undermined. Just because different team members' writing looks the same doesn't necessarily mean that it's written well.

Many testers I have met share the feeling that they are seen as less-than-equals by the development teams they work with. Quality writing is a trait that all professionals seem to appreciate, particularly when the document must stand on its own without the author present to back it up. An author must be confident in and knowledgeable of a topic to write well about it. Quality documentation tells developers and management that the author is a professional, which elevates their perception of the author and of the whole test team.

Pitfalls that Come with Writing
At this point (if you're still reading), you probably think I'm under the impression that writing can solve all the problems testers face on a daily basis. While I do believe that there are a number of things that good writing skills can help resolve or remedy, there are just as many potentially negative effects of writing and written documents. In order to achieve the benefits listed above, it's important to keep possible pitfalls in mind.

I've mentioned templates and document "shells" as potential benefits to a test team. I firmly believe that having a good starting point to work from when writing can significantly reduce the amount of time needed to complete a document and can help the less-experienced writers on your team learn from those with more practice. However, it is easy to be lazy when using a template or sample document. Many people simply copy and paste wording into their new work-template document, even if it is not precisely applicable to the current project.

Another shortcut that can damage the quality of your writing is the assumption that a reader will know or understand what you're trying to say and that you can therefore take shortcuts or omit information. Always assume that the reader will not understand you unless you spell out all of the pertinent details. There's no need to talk down to your audience, but you shouldn't expect them to be able to read your mind, either. Both taking shortcuts and reusing inapplicable sections of text are symptoms of lazy writing. Lazy writing is often a reflection of lazy thinking, and no professional tester can afford to be a lazy thinker, or be seen as a lazy thinker.

The perception that the author of a document is an expert on the subject can help the test team gain equal footing with their development counterparts. However, as a writer, you must always make sure that your writing deserves the "expert" designation. One incorrect expected result or mistaken step in a test case can quickly change someone's opinion both of your work and of you, personally. It's often difficult to build a solid reputation as a professional within the testing field, but it's much more difficult to rebuild that reputation.

One pitfall particularly applicable to test team managers is the assumption that all members of the team are at the same level concerning their writing skills. Remember that each person thinks, and therefore writes, differently. It's important that each member of your team be capable of quality writing when necessary. To help achieve that goal, be sure to take into account the scope and nature of the job when assigning a writing task to a member of your team. Then assign the project to someone who will be challenged but not overwhelmed by it.

When writing as a part of the software testing process, the most dangerous pitfall is equating quality writing with quality planning. It may be tempting to assume that, since you have written a quality, professional document, you have put together an equally good test plan. Remember that the process of planning your test efforts should always take precedence over the process of documenting that plan. No well-written, but ill-conceived, test plan will save your company the millions of dollars lost when a fatal bug is released to the public. And it probably won't save your job, either.

Key Points to Remember
I hope you agree that the ability to write well can provide a number of direct and indirect benefits to your testing efforts. More important, I hope you've found a few new ideas on ways to improve your own writing skills. In the ten years that writing has been a part of my work, I've found that the following things are important to remember each time I write:

• there are no hard-and-fast rules in writing (despite the availability of numerous lists like this one)
• better writing leads to better thinking
• always write in your own voice
• always keep your audience in mind
• use the tools available to you (such as spell-check, grammar-check, and reference books)
• use the people available to you (peer reviews, technical writers' suggestions, and marketing professionals' suggestions)
• always review your work, particularly after several days (when possible)
• writing does get easier with practice, but it never gets easy