Re: where do docs fit in the development process?

[Michael Oboryshko <obie1121 -at- yahoo -dot- com>]

Susie wrote:
> It's painfully obvious that these ppl aren't reviewing stuff,
> but no one seems to care.
Yes, that's exactly right, they don't care. They are busy with
other stuff. I keep telling myself that they hired a tech writer
to care about it so they don't have to. Sometimes it's pretty
hard to keep telling myself that, though.

Instead of having six developers review each iteration of my
docs, I'd rather spend the time doing hands-on testing. I'm
assuming (perhaps wrongly) that you have full access to the
latest development build, source code, and all test
environments.

> and how do you get developers to review your docs?...
Usually I start a project by broadcasting to the team my first
and last request for developer reviews:  "The API guide is in
progress; the latest version is maintained at //address/apiguide
. Please review it at any time. Comments are welcome."  That's
the last time I mention it. Just make sure you keep on working
even if they don't review it.

The neat thing about programmer guides is that you can actually
test the technical accuracy yourself. Not only that, you can
make the calls yourself, capture the actual data returned, and
embed the whole thing as a code sample in your documentation. If
you do it that way, your topic is self-validating.  When
somebody questions your technical accuracy, you will then be in
a position to defend it. So if somebody tells you "That function
doesn't return that value" you can point to the timestamp on
your valid code sample and say; "It returned it last week...Was
it broken then, or is it broken now? Let's test it right now and
see what happens." 

On the other hand, sometimes you need a little open-ended
conversation with an SME, before you can really get started.
It's been said here before, but this really works: Try sending
small chunks of documentation to the specific developer
responsible for that feature. Try walking it in by hand, instead
of email. Then use that as as a starting point for the
open-ended conversation you need to have.

> How is a documentation project initiated? 
In your case, just keep working on whatever you understand the
priorities to be. Don't wait for instructions from above. When
they come it will probably be too late. Sooner or later you will
have one of those meetings where you are supposed to prioritize
all your projects. It's nice to stand up and say "I already
started that; my prototype is on the LAN." 

Regards,
Mike O.

__________________________________________________
Do You Yahoo!?
Great stuff seeking new owners in Yahoo! Auctions! 
http://auctions.yahoo.com

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Attention ForeHelp and Doc-to-Help Users! Upgrade your existing product to
RoboHelp for only $299, through January 31st. RoboHelp can import your
existing Help projects! Learn how else RoboHelp can benefit you. www.ehelp.com/techwr

---
You are currently subscribed to techwr-l as: archive -at- raycomm -dot- com
To unsubscribe send a blank email to leave-techwr-l-obscured -at- lists -dot- raycomm -dot- com
Send administrative questions to ejray -at- raycomm -dot- com -dot-  Visit 
http://www.raycomm.com/techwhirl/ for more resources and info.