Re: Accuracy and phrasing in documentation

[Faith Weber <weber -at- EASI -dot- ENET -dot- DEC -dot- COM>]

Kelly Hoffman writes:

>Seriously, though, this highlights a problem that I suspect many of us
>have faced: what do you do when you have an impossible deadline and
>insufficient information to produce accurate documentation?  Do you
>produce something that's "suitably vague" or "intentionally inaccurate"?
>Do you fight for a more reasonable deadline?  If the latter, what tactics
>have you found to be successful?

Kelly, where I work there's almost always at least one SME on any
project team who's interested in quality documentation. If I
haven't gotten answers about something using normal means, I will
usually write up my own explanation of how the feature works, in
the same amount of detail I'd use if I had the information. Usually
I can make an educated guess, but it's still a guess.

Then I go to the interested SME and show him or her my write-up,
and say "This is what I'm going to put in the manual about such-
and-such. Is this correct?" Somehow, giving the SME the idea that
I'm going to publish something whether or not I get the correct
information is, well, motivating! It's especially motivating when
my guess is completely wrong, because the SME suddenly realizes how
important it is to give me the information I need. (Of course,
the person has to care about the accuracy of the documentation
if this is going to work.)

This technique is a last resort for me, but it works every time!


Faith Weber
weber -at- easi -dot- enet -dot- dec -dot- com