Jeff Atwood once made the observation that[1] ...Of course, the real problem with software development is the users. It's unbelievable. They've caused problems with every program I've ever written.
I can relate, as can most (all?) technical writers. Sometimes it seems as if readers willfully misinterpret your text to be as far removed from what you actually intended as possible. It's ... exasperating.
You write:
This topic describes how to connect to the sample database with an .mdf file.
It's perfectly clear to you, of course, that the database has an .mdf file and that you want to connect to such an .mdf-file-implemented database. But the obtuse reader will look at that and ask "How on earth do I use an .mdf file to connect to a database?"
Or you write:
The template includes common files that are used in many Web applications.
Obviously when you wrote common you meant typical, but yer dumb reader probably will ask "Do you mean the files are shared between applications?"
If they were right there, they could ask and you could clarify. Alas, all they have is your text and the aforementioned tendency to misread you.
Indeed, I do this myself. Here's a set of instructions on the back of a bottle of Fogtech, a product I have extreme need of while motorcycling around in the Seattle winter[2]:- Apply Fogtech® to a completely dry lens.
- Squeeze Fogtech® onto a soft cloth applicator till wet.
- Quckly "paint" a wet coat onto the fogging side of your lenses.
- Stop rubbing! Let dry for 5 seconds.
Remove by washing with plain water.
Here's an approximation of how I, idiot reader that I am, originally read these instructions.- Apply Fogtech® to a completely dry lens.
Aha. Squeeze some from the dropper onto the lens. PS I should clean the lens first, I guess -- ? But dry it.
- Squeeze Fogtech® onto a soft cloth applicator till wet.
Um, so don't squeeze Fogtech® onto the lens -- ? Apparently "Apply" in the first step was not an imperative verb. More, like, "When you apply (later), make sure that ...". Alas, when I see a numbered step that begins with a verb, I assume that they're commanding me to do that verb.
BTW, when I "squeeze till wet," who's getting wet? Probably the applicator. Hopefully not me. Onward.
- Quckly "paint" a wet coat onto the fogging side of your lenses.
Do they mean ... wipe? If so, why didn't they say that? What's the difference between "paint" and wipe? Why the quotes? How do I paint a wet coat onto the lens?
Anyway, which side of the lens fogs ... isn't it, like, all of them?
- Stop rubbing! Let dry for 5 seconds.
Rub? Is that related to quote-paint-unquote? Should I stop painting, whatever that is? Was I supposed to rub? Where did it say that? And, after I let dry for 5 seconds, I do what? What if I wait for 10 seconds before I do ... whatever's next? This is confusing, because the next sentence says ...
Remove by washing with plain water.
Is this part of the procedure? Should I do this now? (After letting it dry for 5 seconds.)
You might think I'm exaggerating here for effect, but actually, not much. (I did get the "till wet" part, in spite of it dangling.) I really do find the instructions somewhat mysterious. The stuff does seem to work if you just wipe it on the lenses, gently. As for the "Remove by washing ..." bit, I went to the Web site to get more details. Which is the latter-day equivalent of having the writer around to ask when you don't understand what they meant, I suppose.
I'm sure that whoever wrote these instructions was 100% clear on every point, and might find it odd that I find them not so clear. ("Dude, it says right there.") The problem with being the reader, tho, is that you are just not smart enough to get that from the text.
Leaving aside that it's harder than it looks to write step-by-step instructions (look at step 1, for example), you have to know what your reader knows and doesn't know. I still don't know what it means to "paint" the goo onto a lens, so I basicaly ignore that (I wipe) and whatever the writer was trying to convey with the odd term and quotes is lost to me.
Writing is hard, and a big reason is that readers are simply not as smart as you, the writer. But you can't make readers any smarter, at least not about how they read your text. So your only option, unfortunately, is to be a better writer.