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:Re: Justification for task-based documentation From:Kris Olberg <kjolberg -at- IX -dot- NETCOM -dot- COM> Date:Fri, 6 Feb 1998 13:55:17 -0600
Chris, most readers of software documentation couldn't care less about WHY
something works the way it does or WHY they are doing a task. They have one
objective: to complete the task. Sometimes the task may be job-related, in
which they probably have a vested interest in completing it as quickly as
possible. They already know WHY they're doing the task. They just want to
know what's required to complete it--no more, no less.
I'm not saying that conceptual documentation is worthless. It can and does
play a role in complex applications. It just should not be intermixed with
task-oriented documentation.
Regards...Kris
------------------------------
kolberg -at- actamed -dot- com
kris -at- olberg -dot- com
-----Original Message-----
From: Chris Hamilton <chamilton -at- gr -dot- com>
To: TECHWR-L -at- LISTSERV -dot- OKSTATE -dot- EDU <TECHWR-L -at- LISTSERV -dot- OKSTATE -dot- EDU>
Date: Friday, February 06, 1998 11:35 AM
Subject: Justification for task-based documentation
>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.
>
>
>
>
