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.
What! I'm not a UNIX gal? Stuart, UNIX was my first love! Just because I
have to accommodate those other platforms nowadays...
As you can see, I'm a bit late in responding :-)
I really don't think we are all disagreeing that much, if at all.
Certainly, I realize that software has deficiencies and that those
deficiencies are often, out of necessity, addressed in the manual or the
release notes. Those are business decisions and we all have to deal with
them -- actually, everyone in every business has to deal with them. What
I meant to emphasize--and perhaps I didn't do a very good job--were
these points:
* A clearly-written procedure can make a bad design painfully
obvious.
* The answer is not always to document the problem -- oftentimes,
the problem can (and should) be fixed.
The second bullet, of course, ties back into the first. I prefer to put
my energy into fixing the design, rather than documenting a bad design.
Isn't documenting bugs as features one of the major cliches/bitter jokes
in the software biz?! Ultimately, design fixes are better for the
customer, but in the meantime, the improvements will be a whole lot
better for everyone else in between as well. I hear an awful lot of
excuses (not from you, Stuart, or anyone in particular on this list)
about how hard it is, how much trouble it will be, how it will never
work, how evil developers are, etc. Now, I'm as much of a cynic as
anyone, but I try not to let that sabotage my work. (Actually, I've
noticed a disturbing trend in my thoughts these days -- I'm becoming
*less* cynical -- gasp! ;-)
In summary: Clear writing always helps, flawed design or not. My
emphasis is that writing can be a great tool to improve, not just hide,
a flawed design.
I suppose I should close with an </soapbox> Sorry about that--I know I'm
preaching to the choir for the most part here ;-)
A.
Alexia Prendergast
Tech Pubs Manager, Seagate Software
Durham NC USA mailto:alexiap -at- seagatesoftware -dot- com
> -----Original Message-----
> From: Stuart Burnfield [SMTP:slb -at- FS -dot- COM -dot- AU]
> Sent: Wednesday, April 29, 1998 2:24 AM
> To: TECHWR-L -at- LISTSERV -dot- OKSTATE -dot- EDU
> Subject: Re: Elegance
>
> It shocked me deeply when Wayne Douglass said:
> > You can't write a manual that's better than the product.
>
> Then, to make matters worse, Alexia Prendergast said:
> > Couldn't agree with Wayne more on this one
>
> It's a disturbing feeling to disagree with Wayne (witty, sensible, a
> Unix guy) and Alexia (not a Unix gal, but witty and even more
> sensible),
> but here goes:
>
