Re: Learning/researching phase of writing

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
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
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
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
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
more alactritously to something they see in print than to questions or

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

Good luck,

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

Previous by Author: Re: How do I show an example?
Next by Author: Re: Gender Reference
Previous by Thread: test
Next by Thread: Learning/researching phase of writing

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

Sponsored Ads