Re: What about Technical Writer vs Communicator?

Subject: Re: What about Technical Writer vs Communicator?
From: Ned Bedinger <doc -at- edwordsmith -dot- com>
To: Gause_Brian -at- emc -dot- com
Date: Tue, 06 May 2008 05:30:26 -0700

Gause_Brian -at- emc -dot- 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 -dot- com
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Create HTML or Microsoft Word content and convert to Help file formats or
printed documentation. Features include support for Windows Vista & 2007
Microsoft Office, team authoring, plus more.
http://www.DocToHelp.com/TechwrlList

True single source, conditional content, PDF export, modular help.
Help & Manual is the most powerful authoring tool for technical
documentation. Boost your productivity! http://www.helpandmanual.com

---
You are currently subscribed to TECHWR-L as archive -at- web -dot- techwr-l -dot- com -dot-

To unsubscribe send a blank email to
techwr-l-unsubscribe -at- lists -dot- techwr-l -dot- com
or visit http://lists.techwr-l.com/mailman/options/techwr-l/archive%40web.techwr-l.com


To subscribe, send a blank email to techwr-l-join -at- lists -dot- techwr-l -dot- com

Send administrative questions to admin -at- techwr-l -dot- com -dot- Visit
http://www.techwr-l.com/ for more resources and info.


Follow-Ups:

References:
RE: What about Technical Writer vs Communicator?: From: Hemstreet, Deborah
RE: What about Technical Writer vs Communicator?: From: Gause_Brian

Previous by Author: Re: Definition of Tech Writer, was STC is broken
Next by Author: Re: Definition of Tech Writer, was STC is broken
Previous by Thread: Re: What about Technical Writer vs Communicator?
Next by Thread: Re: What about Technical Writer vs Communicator?


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

Sponsored Ads


Sponsored Ads