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:Getting information From:Gen Whitt <Gen -dot- Whitt -at- SDINC -dot- COM> Date:Tue, 23 Mar 1999 09:16:38 -0800
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
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
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.
Senior Technical Writer
Software Dynamics, Inc.