Subject: RE: HOW TOs?
From: Steve Shepard <STEVES -at- YARDI -dot- com>
To: "TECHWR-L" <techwr-l -at- lists -dot- raycomm -dot- com>
Date: Thu, 28 Feb 2002 10:00:39 -0800

We develop an accounting system as well. Before I got to the dept, the docs
were originally reference based and organized by the menu and interface
structure. They later tried a more task based approach, but it was more like
just throwing some task information into the reference material. When I came
to the dept we began a more task based approach. Now we have a task based
approach, with overviews at the beginning of each group of related tasks and
our online help as the addition of complete field/button reference material
for every screen.

I say all that to point out that we started where you are. The owner of the
company is a programmer and the docs where reference based partly because of
that. But, over time it became clear from customer feed back that that
wasn't working well and bit by bit we moved to a task based system. But, it
took some trial and error to get there and not without some objections by
some in the company. But, clients are much happier with the docs.

My personal opinion is that a reference based system organized around the
interface is only useful for someone that ALREADY knows the program. It's
very difficult for a novice to find the info he/she needs concerning a
particular task.

But, I think some foundational issues should be examined first. Otherwise
it's just a pissing match about who is right and who is wrong. Rather than
argue the particular merits of each approach, it may help to define the
purpose of the docs. It may be that your manager and you have a different
purpose in mind. His might be, "to provide information about the program."
Yours might be something like, "to help the user accomplish the relevant
tasks using our software." Beginning with those two different statements you
will come up with very different approaches to documenting the application.

By defining the purpose you either understand what he wants and why he wants
it and you go with that, or you provide yourself with the foundation to make
your case. If he agrees that the purpose is help the user accomplish the
relevant tasks using our software, then it may be easier to persuade him of
the benefits to a task based approach.

Start with the foundational issues and work up from there.

Steve Shepard
Technical Communications Manager
Yardi Systems, Inc.
819 Reddick Ave.
Santa Barbara, CA 93103
steves -at- yardi -dot- com

> -----Original Message-----
> From: Radwa Darwish

> The thing is that my boss, who is the software development
> manager, doesn't
> like the "How to...?" approach and wants me to replace it
> with a listing of
> each field, edit box or grid and a brief on its usage. I am
> not quite sure
> that this way will be effective enough and I need your help....Any
> suggestions any innovative techniques or any standardized
> documentation
> process to adhere to.

Now's a great time to buy RoboHelp! You'll get SnagIt screen capture
software and a $200 onsite training voucher FREE when you buy RoboHelp
Office or RoboHelp Enterprise. Hurry, this offer expires February 28, 2002.

You are currently subscribed to techwr-l as: archive -at- raycomm -dot- com
To unsubscribe send a blank email to leave-techwr-l-obscured -at- lists -dot- raycomm -dot- com
Send administrative questions to ejray -at- raycomm -dot- com -dot- Visit for more resources and info.

Previous by Author: Re: Netscape 6x
Next by Author: Re: Hiring Publications Managers
Previous by Thread: Re: HOW TOs?
Next by Thread: Redundancy - Necessary?

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

Sponsored Ads