Getting information

[Gen Whitt <Gen -dot- Whitt -at- SDINC -dot- COM>]

Ben Kovitz wrote:

> A secondary problem is that often people simply haven't thought
> through the information that we need.  For example, I continually
> ask people these questions: "Which users operate this part of the
> software?  When are they supposed to operate it?  Which fields
> should they fill in and which should they leave blank?  Where do
> they get the information that they enter?  What do these field
> labels mean?  What does each value in this pick list mean?"
> Generally people say, "I don't know," but of course this is the
> information that needs to go into a user's manual.  On a good
> day, these questions stimulate people to rethink the user
> interface, showing that it never crossed people's minds to
> address these questions during design.

I have found that there are often situations where the developer simply
doesn't know why the software works a certain way. He was told to add
certain fields, or make something over here change something over there,
and he does it. He doesn't know how this applies to the practical world of
the user. Perhaps regulations changed in the industry, or for some other
reason a change was needed; the reason for the change might not filter down
with the mechanics of the software design. Mostly, it's been in custom
software houses that I've experienced this. Often, the developers would
have little or no knowledge of the actual industry.

Those are the times when you have to trace the string back to the source.
Who wrote the spec? Based on what information? Why was this change needed?
What problem are they trying to solve? It might actually be necessary to go
all the way back to the client to get the question answered; but it's worth
it, because you have to understand the user's situation to write good
documentation. In my experience, usually the project manager relay
communications to the client; but sometimes I got direct contact, a good
thing.

I also found it helps to become familiar with the industry. Usually there
are some industry periodicals around that can be very revealing, and give a
broader viewpoint on how those new features relate to what's going on in
the industry.

Developers know how the software works, but they might not know why someone
wanted it to work like that, and that might be important information for
the documentation. Of course, it's a judgment call how far you take your
research; but if the developer doesn't know the industry, I'd definitely
look around for additional sources of information.

Best,

Gen

Geraldine Whitt
Senior Technical Writer
Software Dynamics, Inc.
Chatsworth, CA

 From ??? -at- ??? Sun Jan 00 00:00:00 0000=