TechWhirl (TECHWR-L) is a resource for technical writing and technical communications professionals of all experience levels and in all industries to share their experiences and acquire information.
For two decades, technical communicators have turned to TechWhirl to ask and answer questions about the always-changing world of technical communications, such as tools, skills, career paths, methodologies, and emerging industries. The TechWhirl Archives and magazine, created for, by and about technical writers, offer a wealth of knowledge to everyone with an interest in any aspect of technical communications.
> 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. http://www.doctohelp.com/SuperPages/Webcasts/
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! http://www.helpandmanual.com/
---
You are currently subscribed to TECHWR-L as archive -at- web -dot- techwr-l -dot- com -dot-
