Re: Accuracy and phrasing in documentation

[Len Olszewski <saslpo -at- UNX -dot- SAS -dot- COM>]

Faith Weber replies to Kelly Hoffman:


> 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 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?"

[...]

We do this routinely here, especially on primary reference. After two
cycles of technical review, we identify the SME *responsible* for the
product documented in each section, and have the SME initial the final
draft, "signging off" on the information it contains. I've taken to
calling these "final signoff reviews" in the cover memos. It tends to
focus the attention of the SME's, the key words in the cover memo being
phrases like "you are responsible" and "final signoff". Usually, I give
developers something like 48 hours to complete the review, and I pick
them up personally, reminding reviewers to initial and date each page.

I haven't had to cancel shipping a book to the printer yet, and even
though I've had some errors, they haven't been very common. I think this
creates a real feeling of teamwork when handled correctly and
professionally. After all, it's not just *my* responsibility, the SME
has a stake in it too. And it's really not just *my* book either, the
reviewers contribute just as surely and as importantly as the writers,
editors, proofreaders, compositors, and on down the line.

|Len Olszewski, Technical Writer |"You can observe a lot by watching."|
|saslpo -at- unx -dot- sas -dot- com|Cary, NC, USA|     - Yogi Berra                   |
|---------------------------------------------------------------------|
| Opinions this ludicrous are mine. Reasonable opinions will cost you.|