TechWhirl (TECHWR-L) is a resource for technical writing and technical communications professionals of all experience levels and in all industries to share their experiences and acquire information.
For two decades, technical communicators have turned to TechWhirl to ask and answer questions about the always-changing world of technical communications, such as tools, skills, career paths, methodologies, and emerging industries. The TechWhirl Archives and magazine, created for, by and about technical writers, offer a wealth of knowledge to everyone with an interest in any aspect of technical communications.
Subject:Documenting Bad Design From:"Huber, Mike" <Mike -dot- Huber -at- SOFTWARE -dot- ROCKWELL -dot- COM> Date:Thu, 16 Nov 1995 12:01:17 -0500
I use the "bland and factual" approach for the release documents,
but sometimes issue an
"internal application note" with "Do Not Release" all over it that
uses the same bland and factual tone but gets ugly about it.
Includes the way it's been done by others. Strings all the steps
in the work-around into one long numbered list. Points out the
pitfalls that the user is likely to encounter. I make no effort to ease
the process or spare anyone grief. But I never break out
of the bland and factual tone in one of these, because I distribute
them to engineering, management, and tech support.
Sorry - that's a lie. I just looked at the only one (we aren't perfect
here, but we do tend to fix things before we send them out)
of these I've had to do, and it includes the following:
"{product X} uses the method described as follows, apparently
because our customers need finger exercise, or perhaps as
homage to the evil Data Stream gods:"
But the rest of it is pretty clean.
----------
From: Robert Plamondon[SMTP:robert -at- PLAMONDON -dot- COM]
Sent: Thursday, November 16, 1995 10:08 AM
To: Multiple recipients of list TEC
Subject: Re: TECHWR-L Digest - 14 Nov 1995 to 15
>The recent thread about writing for beta releases made me wonder how
other
>technical writers write around design flaws. I'm not talking about
stuff
>that will be corrected before the final version goes out the door, and
I'm
>not talking about a few bugs in a program. I'm interested in how people
>write around serious flaws for which there is no logical explanation.
And,
>for the sake of discussion, let's assume that there is no way to get rid
of
>these design flaws.
You write about them in a bland and factual manner, calmly giving
the tortuous workarounds, and altogether hiding the fact that the
stupidity of the Powers That Be fills you with indignation (or
even rage).
The readers are perfectly capable of saying, "This stinks" without
our help.
-- Robert
--
Robert Plamondon * President/Managing Editor, High-Tech Technical
Writing,
Inc.
36475 Norton Creek Road * Blodgett * Oregon * 97326
robert -at- plamondon -dot- com * (541) 453-5841 * Fax: (541) 453-4139
