How Thinking Like a Technical Writer can Make you a Better Tester

Technical writers have many skills and uses, which mostly strike testers as irrelevant to the actual world of software. In fact, most of their skills should be studied by testers and, if at all possible, programmers.


Because technical writers have to explain the reasons behind any particular behavior to their readers, they’re very good at spotting inexplicable behavior. This is, to me, their most enviable skill. Often, it will take a technical writer less than two minutes to frown at the new behavior, and only a little while more to e-mail you a WTF?.

Now, in an ideal world, this shouldn’t happen. The behavior had been scrutinized by at least one specification-writer, programer and tester; often, in fact, it will go through more than half a dozen people before it reaches the tester. So how did everyone else miss the logical gap?

The simple answer is that not one of them – not even the spec-writer – thought like a user; only the technical writer, struggling to write the user guide, went in that direction. Everyone else along the chain was writing to software people. The spec-writer was speaking in technical terms to the development department; the programmers were speaking among themselves in code; and the testers went back to the technical lingo of the spec-writer.

So, next time you’re about to test a new feature, try to explain it to a technophobe layman. Can’t? Then re-think approving this feature before someone clarifies it.


Technical writers are also great at spotting inconsistencies in the module. Everything from technical terms (their bread and butter) to more complex logical clashes catches their eye, and it’s a neat trick well worth learning.

So, how do they do it? By taking a step back from the current feature to previous features and asking themselves whether there’s something in the module that already touches this aspect. If there is, they move forward: Do both features use the same terms? If the terms are new, should they be new, or should the programmer have used the old ones?; Do both features rely on the same logic? Is there justification for two sets of logic, or did someone screw up? Remember, it’s possible that the programmer never even knew the old logic existed; Is the feature where it’s supposed to be? The other feature dealing with this aspect is in a different module, or a different part of this module. Why was this moved here? And so on. You get the picture, I’m sure. The idea is to look for differences, and see if they’re justified.

True, they deal with entire modules and you often with just a certain aspect of that module, so they may always best you at this game. Still, these inconsistencies are fundamental flaws in the software – and every one you manage to find before it reaches the writers and returns two or three days before the release is a blessing.


GUI is often considered the step-child of testing; I think it’s every bit as important as testing the logic, since the user encounters – and is able to judge – the GUI first and always. And, once again, GUI testing is something technical writers got wrapped around their little finger. This is partially because they have to explain the window – often field by field and button by button – and partially because they work with the screen caps and so get a moment to look at the window without working in it. These are two steps every tester should adopt while testing.

First, take a moment to look at the window without doing anything. Things will start jumping out at you – crocked fields, cut text, table headers floating awkwardly above and slightly to the side of their table. Even, if you pay careful attention, some of the inconsistencies we spoke of earlier. Is something you call Test in dozens of windows suddenly an Exam? Is something that’s supposed to be a combo-box a simple text field? No reason you shouldn’t be able to spot these mistakes.

Next, go over each field and button and check that they’re where they’re supposed to be and do what they’re supposed to do. This is even more crucial when you’re working with a module that might come in more than one language – and critical when one of these languages is going in a different direction (the right-to-left languages, most notably Arabic and Hebrew).

Writing about the Module

Yes, not at all your job. Still, you do an awful lot of it, day to day – bug reports, e-mails, testing documents – so wouldn’t you like to know how to do it an neatly as a technical writer? It’s not just their command of the language or their love of the tedious explanations that makes their writing so easy to follow. It’s a few simple ground rules.

1. Things have names – use them. That test is still a test, not an exam. Don’t confuse your reader by referring to drop-down menus as regular menus, to field groups as single fields or to keyboard keys as buttons (buttons are in the window; keyboard keys are.. well.. keys).

2. Actions have names, too. Entering data and saving data are two different actions; clearing data from the field and deleting it from the database are also distinctly separate.

3. Things have locations. Got a busy form with lots of fields and only one won’t write to the database? If that field is numbered, you’ve hit jackpot. If it’s not, name it clearly – and correctly – then take a screen cap, circle the field, and in your bug report write “in the lower left quadrant”

Once again, I’m sure you’re getting the hang of things without need to have them spelled out. The idea is to try and create a consistency between your writing and the system, and between your writing day in and day out, to minimize confusion; and also, to give as much information as possible, so that people don’t go looking at the wrong part of the module.

For more information, ask your friendly neighborhood technical writer for tips; or at least find out which websites he cruises for tricks of the trade.

This entry was posted in Articles, QA and tagged . Bookmark the permalink.

Leave a Reply

Please log in using one of these methods to post your comment: Logo

You are commenting using your account. Log Out /  Change )

Google+ photo

You are commenting using your Google+ account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s