Justification for task-based documentation

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

Previous by Author: Re: Problems with hiring, Equity
Next by Author: Re: Producing Books
Previous by Thread: Paper/Copy Quality Summary
Next by Thread: Re: Justification for task-based documentation

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

Sponsored Ads

Sponsored Ads