What about Technical Writer vs Communicator?

[Ned Bedinger]

Gause_Brian at emc.com wrote:

> For anyone who thinks risks are lower for technical documentation than
> for business documentation, I would recommend a few months documenting
> an API or an SDK. In some technical documents, if even a single letter
> is wrong (in a code sample, say), then the meaning is entirely lost. If
> the method call is misnamed, the user may never get the code sample to
> work.

My experience is that API documentation users are among the most 
resourcefully self-sufficient of audiences. If something doesn't work as 
documented, the error message, declaration, or googling will turn up a 
lead. I've heard API and SDK developers wonder why "documentation" is 
even necessary.

That said, I, the tireless learner, would hugely appreciate correct code 
examples, because I want to be confident in the documentation. When 
example code isn't maintained while the APIs change, for example, it 
leads me into the negative expectations for the documentation, which in 
turn makes it more likely that I'll misread something that is correct, 
and not catch it because I'm expecting the documentation to be wrong. It 
makes something I expect to be straightforward into a mind game. What a 
surprise.

While we sometimes wish for 100% accuracy, it seems costs and other 
pressures often set the bar much lower, even for major developer 
products from major vendors.

> That's 100% failure, and to say that the correct answer can be
> trained or re-written is simply a mistake.

I'm sure there are quality-conscious API developers and their tech 
writers who have the highest standards for documentation and code, but 
bugs do happen in both. Beating yourself up about it won't get you to 
100%. But those of us who use the documentation do appreciate the sentiment.

Ned Bedinger
doc at edwordsmith.com