Re: Elegance

Subject: Re: Elegance
From: Ronni Geist <ronni -at- GEISTWRITERS -dot- COM>
Date: Thu, 23 Apr 1998 18:19:46 -0400

I find this **very** interesting...

Offline I'm receiving comments like "Ronni, I couldn't agree with you
more!" "I'm working on a similar project right now!"

While online the responses are very different!

To Alexia and Wayne who say...

> good docs will uncover flawed designs.
I say, you're absolutely right -- good docs reveal flawed designs.
However, the reality is that when you're the doc manager of a
hardware/software company and the president says: "Here's the product,
this is the deadline, get it out the door on schedule or you'll be out
the door!!" and the programmers say, "It works as designed!" or "We'll
fix that in the next rev!" flawed designs or not, you've gotta document
it to make it look as good as possible.
Does that happen frequently? Damn right...a whole lot more than most
of us would like to admit. Profits margins, deadlines for trade shows,
OEM contracts, the volatility of the industry -- there are lots of
reasons why products go out the door flawed or "before their time."

Wayne says...

> If the installation procedure sucks, your manual will map it exactly.

> And it will look like the kludge that it is.
Not necessarily. You can break down a complex install into smaller
chunks...or explain things to users along the way to keep them on
track... There are lots of things you can do to make a less-than-perfect
product look better. No, that's not fixing the problem, but I'm not a
programmer/engineer. I'm a doc writer/editor/manager, and I see my job
as making things better/easier for users, even if it means documenting
less than perfect products.

Alexia says:

> as Wayne pointed out, never underestimate your users. Fatal mistake.
Is making a program appear to be less flawed than it is
underestimating your users. No, I don't think so!

I maintain a file of reviews of the products I've done docs for, to show
to prospective clients and headhunters. To cite a couple of examples...

* For a system which I documented a while back, "PC Magazine"
wrote: "Its outstanding documentation makes the initial stages of
setup and learning much smoother than they would be with most other

* For a peripheral I recently worked on, the review states that the
card did things well -- and "with class" -- thanks in part to the
"helpful documentation."

It's not an ideal world out there. There's a whole lot of
less-than-perfect hardware and software on the market. I may not be able
to fix the product, but I can create documentation that makes the
product look less awful than it really is.

So returning to Wayne's original comment...

> You can't write a manual that's better than the product.

I still think you can...and I've got the reviews to substantiate it! ;-)


Ms. Ronni Geist
Director, Editorial Services
ronni -at- geistwriters -dot- com

Previous by Author: Re: Elegance
Next by Author: Re: Software button removed after documentation is sent to printer
Previous by Thread: Re: Elegance
Next by Thread: Re: Elegance

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

Sponsored Ads