Documenting Bad Design

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
>technical writers write around design flaws. I'm not talking about
>that will be corrected before the final version goes out the door, and
>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.
>for the sake of discussion, let's assume that there is no way to get rid
>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
36475 Norton Creek Road * Blodgett * Oregon * 97326
robert -at- plamondon -dot- com * (541) 453-5841 * Fax: (541) 453-4139

Previous by Author: Re: Lock, Freeze, Hang, Crash?
Next by Author: Re: Death of Apostrophe/sick hyphen
Previous by Thread: Re: TECHWR-L Digest - 14 Nov 1995 to 15 Nov 1995
Next by Thread: Punctuation and Hypertext

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

Sponsored Ads