Re[2]: accuracy & phrasing in documentation

Subject: Re[2]: accuracy & phrasing in documentation
From: Susan Gallagher <Susan_Gallagher_at_Enfin-SD -at- RELAY -dot- PROTEON -dot- COM>
Date: Tue, 26 Oct 1993 15:10:00 EST

Reply to:

kelly -at- nashua -dot- hp -dot- com (Kelly Hoffman) Message-Id:
<9310261757 -dot- AA02179 -at- bigbird -dot- metrix -dot- com> SMTP-CCMail
translator Ver: acm 2.73 8/18/93

original message:
--------------------------------------------------------------------------------
I asked for a distinction between "intentionally inaccurate" and
"suitably vague."

Susan_Gallagher_at_Enfin-SD -at- relay -dot- proteon -dot- com writes:

> Suitably vague is when...

> You need to describe a process for which the software is not
> completely developed and you're not exactly sure how it will
> work (i.e., when you're stuck documenting vaporware).

> The software developer left the company last month and no one
> is quite sure yet how the stuff he left behind works, but the
> doc is overdue.

Ok, from these examples, I infer that "suitably vague" is when you're
"intentionally inaccurate" because it's not possible to write accurate
information in the allocated time. But, from an earlier post, we learned
that it's "***never*** acceptable to be intentionally inaccurate."

Houston, we have a problem....

(lotsa smiley faces go here, in case it's not obvious :-)

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

-------------------------------------------------------------------
----- end original message

No, no, no!!! Being suitably vague means being as accurate as you
can possibly be without including the phrase "beats the s**t out of
me" in the documentation!!! There's a lot of that kind of thing
that goes on around here since we just merged and lost some of the
original system developers and the above mentioned brutally
accurate phrase is an answer you sometimes get from the senior
development staff!!!

As far as unreasonable deadlines are concerned, I don't think you
can ever avoid those. Usually there are good reasons for the
deadlines (read economic) and neither programming nor doc staff
like them much. You cope. You do the best you can and hope to
catch up in the next rev. Realistically, if they waited until the
product was bug free and the doc was typo free before they released
a piece of software, we'd all be breathlessly awaiting the release
of WordStar for CP/M!!!

I guess my point is, and I'm now being explicit so pay attention
8-} -- as technical communicators we have a dual responsibility:

To our readers, to be as truthful and accurate as possible.

To our employers (from whence all paychecks eminate) to
present the product in the best light possible.

When you have wrestled with this moral alligator and lived to tell
the story, you can begin to understand the meaning of the phrase
"suitably vague."

Sue Gallagher at Enfin-SD


Previous by Author: Re[2]: Q: Converting Word Doc to ASCII for E-Mailing
Next by Author: Re: help on writing-editing work flow
Previous by Thread: Re: accuracy & phrasing in documentation
Next by Thread: Re: Re[2]: accuracy & phrasing in documentation


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


Sponsored Ads