Re: Learning/researching phase of writing

[Mike Pope <mikep -at- ASYMETRIX -dot- COM>]

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
you
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
usually
on that plane while they're coding. However, you can:

* read the spec, if it exists and was specifically written to address these
questions
* talk the project lead or marketing person (or whoever), the person charged
with
   knowing this type of info
* ask for presentations on specific topics, stressing that you need to know
about the
  topic from the ground up. I find that this works very well around here.
For example,
  we might be implementing, oh I dunno, a full-text search engine. Could one
of the
  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
described to
you by the programmer. You won't know what the user (your reader) needs to
know
until you've tried to do it yourself. The downside -- one of them, anyway --
is that
you're often working with software that's very fragile and only marginally
functional,
which can be confusing and is very time-consuming.

I try limit my interviews with programmers to very specific questions only,
for instance,
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
which the
answers are very concrete.

Let me emphasize again that I'm speaking only from personal experience. A
more
general rule I would propose is that you just try to hang around the
programmers as
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
think they've
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
respond
more alactritously to something they see in print than to questions or
emails.

Sorry, probably time to stop the random mind-dump.

Good luck,

 -- Mike Pope
mikep -at- asymetrix -dot- com