RE: Use of Optional in instructions

Subject: RE: Use of Optional in instructions
From: "McLauchlan, Kevin" <Kevin -dot- McLauchlan -at- safenet-inc -dot- com>
To: "techwr-l -at- lists -dot- techwr-l -dot- com" <techwr-l -at- lists -dot- techwr-l -dot- com>
Date: Wed, 16 Sep 2009 10:05:18 -0400

Robert Lauriston said:

> I'm not sure I've ever seen a help topic that didn't start with a
> description of what the steps that follow will accomplish.
> If the topic's written well, it shouldn't matter whether you get there
> by invoking a context link, choosing an entry in the TOC, index, or
> search results, or following a cross-reference from another topic.

The discussion is about:

a) whether "well-written" DOES in fact include that sort of thing at the beginning, or whether that would be considered eye-glazing dreck that most readers wouldn't get through, on the way to something that looked like "this is what I need to DO";

b) whether most readers actually see the intro or just skim to something that looks like a step 2 (since even step 1 of most instructions is usually "centering" fluff and the meat starts at step 2 or 3 and you read only three words of it anyway to get the gist and then just wing it from there....

In other words, we've been beating around the notion that well-written and "I'm not sure I've ever seen... that didn't..." might not be the same thing. Partly, we've been chatting about whether the argument from tradition should carry more or less weight (though not spoken explicitly in those terms until just now).

And somebody had the nerve to ask for research and study results, instead of just informed opinion. Sounds good until you realize:

a) how little of that there is

b) how big (and expensive) a task it is, which accounts for "a)".

The reason that there can be all kinds of studies and meta-studies for things like pharmaceuticals and virtually none for things like "how people use instructions/help" is that there's a big pay-off for enduring the expense (time, money, human resources) in the drug biz, and no pay-off at all in the writing-instructions-and-help biz.

The only aspect of writing that pays off, across the board is clarity - viewed after the fact by a judge - when liability rears its head. In most cases, we can't even make the argument that better docs will save money for the company, because most companies have learned to make Customer Support a profit center. Similarly, our niche is not directly comparable to Education (at least, not as government undertakes it), so there's no pay-off in that direction either.

So, there's no incentive for any company or organization-of-companies to fund all the expensive, inventively-crafted double-blind studies that would prove the best approaches and disprove the old-wives-tales and tradition and who-markets-their-latest-flavor-better by which we (as a sub-industry) operate.

Possibly the most likely places for such funding would be the military and the lives-will-be-lost industries, that take the long view. But that kind of long view means that change comes slower than many of our working lifetimes.

- Kevin

The information contained in this electronic mail transmission
may be privileged and confidential, and therefore, protected
from disclosure. If you have received this communication in
error, please notify us immediately by replying to this
message and deleting it from your computer without copying
or disclosing it.


Free Software Documentation Project Web Cast: Covers developing Table of
Contents, Context IDs, and Index, as well as Doc-To-Help
2009 tips, tricks, and best practices.

Help & Manual 5: The complete help authoring tool for individual
authors and teams. Professional power, intuitive interface. Write
once, publish to 8 formats. Multi-user authoring and version control!

You are currently subscribed to TECHWR-L as archive -at- web -dot- techwr-l -dot- com -dot-

To unsubscribe send a blank email to
techwr-l-unsubscribe -at- lists -dot- techwr-l -dot- com
or visit

To subscribe, send a blank email to techwr-l-join -at- lists -dot- techwr-l -dot- com

Send administrative questions to admin -at- techwr-l -dot- com -dot- Visit for more resources and info.

Please move off-topic discussions to the Chat list, at:

Use of Optional in instructions: From: Bruce Megan (ST-CO/ENG2.2)
RE: Use of Optional in instructions: From: Combs, Richard
RE: Use of Optional in instructions: From: Boudreaux, Madelyn (GE Healthcare, consultant)
Re: Use of Optional in instructions: From: Lauren
RE: Use of Optional in instructions: From: McLauchlan, Kevin
Re: Use of Optional in instructions: From: Robert Lauriston

Previous by Author: RE: Use of Optional in instructions
Next by Author: RE: Use of Optional in instructions
Previous by Thread: RE: Use of Optional in instructions
Next by Thread: RE: Use of Optional in instructions

What this post helpful? Share it with friends and colleagues:

Sponsored Ads