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.
Just reading yesterday's digest and was reminded of a funny thing that
happened last week. Keep what David said in mind - quality depends on
your readers' purpose... a document is only useful within the context of
this purpose (or words to that effect...)
We are remodeling a bathroom. My job, during last week's vacation, was
that of official adhesive mixer. Mortar, wood filler, thin set, grout,
epoxy... depending on what we were doing, I mixed and my husband
applied. The instructions provided were very vague, and provided no
context. So, we went to the manufacturer's website and viewed a video,
where the installer directed us to "trim" any mortar that oozed out from
beneath the pan.
Use of the word "trim" inferred that mixture should be fairly thick but
malleable, sort of like raw cookie dough, would you agree? But the
instructions did not provide that analogy. What we had was not
"trimmable" in the least. It was much muddier and mushier than that,
leading to a hot-tempered panic attack where my husband searched for the
mortar company's 800 number, wondering whether the shower pan would fall
through the floor the first time we used it...
Then, there was the finger-pointing at me...he concluded I did not
follow directions and therefore, mixed the compound incorrectly.
He ended up pulling it up, cleaning it all off, and starting over,
with... (wait for it)...
...precisely the same results!
(Brief aside: any aspiring television producers out there might consider
a new reality show based on husbands and wives doing home improvement
projects together...Survivor? HA!)
Quality is notoriously difficult to define because it is so subjective -
regardless of whether it's quality in technical documents, widgets, or
automobiles. This is why we Hyundai and Ferrari can coexist in a market
- people define quality in different ways.
The key is to know your audience and then deliver a product that meets
and hopefully exceeds their expectations. It was clear to us that the
mortar directions provided were intended for contractors, not weekend
warriors like us. We lack the experience and the skills necessary to
recognize when mortar is incorrectly mixed - too much liquid or not
enough can both have disastrous results. (See? Know your audience.)
In our case, it would have been great if the mortar directions had
provided some sort of range to know whether we were doing this right.
Photos, more descriptive examples, even a warning would have helped.
Having said that, it's far too easy and tempting to fall into the trap
of measuring the things that are "easy" and calling that quality. Things
like typos per page, readability statistics, etc. are easy to measure
and really don't mean much in the real world, if, as John pointed out,
your users can still perform the tasks they need to perform. Plus,
editing for the "typo-free" document adds significant cost to a
documentation project, but does that cost result in any gains? Doubtful.
For help toward this, pick up any of Ginny Redish's or JoAnn Hackos'
books... I think the optimal way to approach this is by thoroughly
understanding your audience and then striving to deliver what they need
to be successful.
ComponentOne Doc-To-Help 2009 is your all-in-one authoring and publishing
solution. Author in Doc-To-Help's XML-based editor, Microsoft Word or
HTML and publish to the Web, Help systems or printed manuals. http://www.doctohelp.com
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-
