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.
Subject:Justification for task-based documentation From:Chris Hamilton <chamilton -at- GR -dot- COM> Date:Fri, 6 Feb 1998 10:43:14 -0600
Good day everyone--
I have to meet this afternoon with the man who tells me how to do my
job. Our product is rather complex. Among the things it includes are a
series of utilities that help you do some of the things you need to do.
We have a Utilities Guide that tells you how to do every possible thing
with each utility, then an Administrator's Guide and a Developer's Guide
that tell you how to do the things you need to do to administrate or
develop with our product.
The Admin and Developer's Guides also talk about the utilities, telling
people specifically how to use the Utilities to perform the task at
hand. This results in duplication of information.
What this guy has, I think, decided, is that you should tell people
about the conceptual things behind each task, then refer them to the
Utilities Guide for directions on how to use the Utility, basically
reducing the Developer's Guide and Administrator's Guides into
conceptual, not task-based documentation. (I submit that people using
software will not read documentation that is strictly conceptual.)
I need help. I need more justification than "because I said so" to
support the task-based documentation. Removing the task-based stuff will
result in a significant amount of extra work (for all that time I might
otherwise spend sleeping at night) and will significantly, in my
opinion, reduce the quality of the documentation.
Chris
--
Chris Hamilton, Sr. Technical Writer chamilton -at- gr -dot- com
Greenbrier & Russel http://www.gr.com
-------------------------
These views are mine, not my employer's.
