About

I'm Mike Pope. I live in the Seattle area. I've been a technical writer and editor for over 30 years. I'm interested in software, language, music, movies, books, motorcycles, travel, and ... well, lots of stuff.

Read more ...

Blog Search


(Supports AND)

Google Ads

Feed

Subscribe to the RSS feed for this blog.

See this post for info on full versus truncated feeds.

Quote

The reason why so few good books are written is that so few people who can write know anything.

Walter Bagehot



Navigation





<October 2020>
SMTWTFS
27282930123
45678910
11121314151617
18192021222324
25262728293031
1234567

Categories

  RSS  
  RSS  
  RSS  
  RSS  
  RSS  
  RSS  
  RSS  
  RSS  
  RSS  
  RSS  
  RSS  
  RSS  
  RSS  
  RSS  
  RSS  
  RSS  
  RSS  
  RSS  
  RSS  
  RSS  
  RSS  
  RSS  
  RSS  
  RSS  
  RSS  
  RSS  
  RSS  
  RSS  

Contact Me

Email me

Blog Statistics

Dates
First entry - 6/27/2003
Most recent entry - 10/11/2020

Totals
Posts - 2629
Comments - 2638
Hits - 2,311,246

Averages
Entries/day - 0.42
Comments/entry - 1.00
Hits/day - 366

Updated every 30 minutes. Last: 9:07 AM Pacific


  07:13 PM

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]:
  1. Apply Fogtech® to a completely dry lens.
  2. Squeeze Fogtech® onto a soft cloth applicator till wet.
  3. Quckly "paint" a wet coat onto the fogging side of your lenses.
  4. 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.
  1. 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.

  2. 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.


  3. 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?


  4. 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.


[1] Being Jeff, he was rebuking programmers, not users. Probably that's clear.

[2] Not only do I wear a helmet that has a faceshield, but I wear glasses and sometimes (haha, in Seattle in winter?) sunglasses.

[categories]  

[2] |