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:Re: Learning/researching phase of writing From:Mike Pope <mikep -at- ASYMETRIX -dot- COM> Date:Thu, 19 May 1994 15:18:00 PDT
Erik Larsen asks:
>What do you find most beneficial: Interviewing developers, hands-on
>experience with a beta product, looking at actual code, design specs, etc.?
In my case, the short answer is: all of the above. It depends on how much
already know and what you're after. You need to find out what the purpose
is of the software you're documenting, who the audience is, what problems
it solves, etc. Talking to programmers often doesn't help; they're not
on that plane while they're coding. However, you can:
* read the spec, if it exists and was specifically written to address these
* talk the project lead or marketing person (or whoever), the person charged
knowing this type of info
* ask for presentations on specific topics, stressing that you need to know
topic from the ground up. I find that this works very well around here.
we might be implementing, oh I dunno, a full-text search engine. Could one
programmers spend an hour telling us what's it for, how it works, etc.?
The next step is to be able to work with the product. In my experience,
there is no
substitute, no matter how clearly the spec is written or how well it's
you by the programmer. You won't know what the user (your reader) needs to
until you've tried to do it yourself. The downside -- one of them, anyway --
you're often working with software that's very fragile and only marginally
which can be confusing and is very time-consuming.
I try limit my interviews with programmers to very specific questions only,
I know what this bit of the software is supposed to do, and I tried running
it, but I'm
getting such-and-this response -- what's the deal. You know, questions to
answers are very concrete.
Let me emphasize again that I'm speaking only from personal experience. A
general rule I would propose is that you just try to hang around the
much as possible (if your company encourages co-location, for example). Stay
in their faces, ask lots of questions, be sure to let them know when you
done a cool thing. Do your homework first, of course -- that is, if you ask
lots of questions, try not to ask too many dumb ones. <g> Get them to read
bits of your doc that describe the piece they're working on -- they'll often
more alactritously to something they see in print than to questions or
Sorry, probably time to stop the random mind-dump.