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.
At 12:25 PM -0700 5/19/2000, Andrew Plato wrote:
>Therefore, the precursor to all decent documents is data: raw, ungainly
>information. At the bare minimum, documentation must contain this raw, ugly
>data in some form. Otherwise, the document is totally worthless.
>
>Beyond the raw data is where we come in. We force that data to make sense.
>Either by organization, task lists, pretty pictures - whatever. Engineers
>aren't very good at this stuff. So, they need you to do it.
Hmm. Andrew, are you saying that's it's usual for you to have engineers
provide the raw data about how an application works? It's sure not usual
for me. Even for reference work, I get most of that raw data by using the
application, and pester the developer only for answers to questions I can't
find out on my own.
>So, if you try and build a document without the raw data, you'll have an
>exquisite pile of crap. If you have only raw data, you'll have a pile of crap
>that at least has information in it. Therefore, you must have both: reference
>and tasks. But if you can't then you at least need the raw material. Tasks
>with
>out reference are cute - but don't deliver enough content.
Depends on the application, surely. If I'm documenting a development
environment (which I am, at the moment, as it happens), then I agree the
language reference needs to take priority over the "How the heck do I make
this thing do such-and-such?" information. Not only does the programmer
turn often to reference information, but it's not possible to include
everything about the language in the task-based information. Documentation
for a product like this would, by its nature, be incomplete if it didn't
include a language reference.
But if I'm documenting, say, a billing application, the "reference" is
going to consist of things like lists of menu items and information about
dialog-box controls. It's potentially helpful to some users, yes...but not
as useful as task-based help. The documentation for any product needs to be
accurate and useful, and while reference help for this kind of application
can be just as accurate as the task-based help, and it might even cover as
much territory as the task-based help, it's not going to be anywhere near
as useful. Here starting with the reference would be a mistake, because
it's likely to be less complete and certain to be less useful than its
task-based counterpart.
