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.
This is the part I disagree with. The questions that need to be asked are the
same for all documents. What is different for different documents is the extent
to which the answers influence the form and content of the document. You may
not be writing about the "business aspects" of what the product is designed to
do, why the customer/user wants the product or what the customer/user wants to
accomplish with the product, but you still need to ask about these things and
know what they are, because they determine (or should determine) how the
procedural information is presented and organized, or in some cases whether
certain procedural information is provided at all.
I have a shelf full of ponderous tomes masquerading as software user manuals
that document every function their applications are capable of performing, with
no distinction made between those functions that serve the needs of the most
common "bread and butter" paying customers and those that are of interest only
to the most advanced power users. In some cases, the companies that made the
applications have long since eliminated their printed documents, laid off their
in-house writers and now only provide offshore-produced online help, with the
result being equally useless because I can't find the help for a command until
after I've managed to find where the command is buried in the UI. In all of
these cases, I can usually type the name of the application and my specific
question into Google and find the answer I need posted by some other equally
frustrated user who finally managed to figure it out faster than I can find it
in either the printed manuals or the online help. I don't know if the problem
with these documents is that their writers failed to ask about the "business
aspects" of the products, or if they just documented everything in sight as
"defensive writing" because the company's developers and product managers
couldn't answer those questions, but either way the result is some of the worst
user documentation I have ever encountered and is all but worthless to me as a
customer/user (though I do sometimes make use of them as examples of how not to
write when coaching new writers).
Gene Kim-Eng
----- Original Message -----
From: "Keith Hood" <klhra -at- yahoo -dot- com>
It is a matter of asking different questions for different documents, because
they do not serve the same purposes, so the thinking about how to structure them
is different.
Are you looking for one documentation tool that does it all? Author,
build, test, and publish your Help files with just one easy-to-use tool.
Try the latest Doc-To-Help 2009 v3 risk-free for 30-days at: 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-
