Re: Justification for task-based documentation

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.

kolberg -at- actamed -dot- com
kris -at- olberg -dot- com

-----Original Message-----
From: Chris Hamilton <chamilton -at- gr -dot- com>
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 Hamilton, Sr. Technical Writer chamilton -at- gr -dot- com
>Greenbrier & Russel
>These views are mine, not my employer's.

Previous by Author: Re: Documenting from Program Specs
Next by Author: Re: Programming Languages for Technical Communication
Previous by Thread: Justification for task-based documentation
Next by Thread: Update: Delivering Docs Electronically

What this post helpful? Share it with friends and colleagues:

Sponsored Ads

Sponsored Ads