Re: Elegance

Subject: Re: Elegance
From: Alexia Prendergast <alexiap -at- SEAGATESOFTWARE -dot- COM>
Date: Tue, 5 May 1998 17:32:29 -0400

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
* 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 ;-)


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:

Previous by Author: telephone number formats
Next by Author: JOB: tech writer: RTP: NC: Seagate Software: cross posted to tech wr-l and framers
Previous by Thread: Re: Elegance
Next by Thread: The documentation process - step-by-step

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

Sponsored Ads