Re: creativity . . . and ethics

[Len Olszewski <saslpo -at- UNX -dot- SAS -dot- COM>]

Quoting John Sanders, who is talking about Steve Hollander, who is
talking about Maria Townsley (with liberal deletions throughout):

[...]
> The manual also acts as a company's voice
> in how the product can be used, what the user needs to know, and all the
> ins-and-outs of the routine use of the thing.
[...]
> But the
> point is that people are trying to sell something, and the manual is just as
> much a part of the product as the product itself (it get's fuzzy).

> Is this an unwarranted view?
[...]
> Sure, we'd all like to tell it exactly like it is, or should I say present
> our information in the purest possible light, but that would get some of us
> quickly reprimanded, if not fired out right.

[...]
> Have I missed the boat here? Is lightning going to strike me down?

> Let me know.

No, no, you haven't missed the boat at all. But there's more to say
about it, I think.

Now, HERE'S a juicy topic for those of us in the private sector; just
how much of what we write is marketing-oriented, how much is the truth,
and is there any overlap 8-)? Allow me to sidestep this question....

I think it's true that, to the extent we work for companies who must sell
something to pay our salaries, we have a certain *financial* interest in
helping the company sell as much as possible. Certainly, portraying
company products in the documentation positvely seems reasonable. OTOH,
depending on the company, the corporate culture, etc., isn't it better
in the long run to try and make the product itself better? I would say
so.

How do writers go about making the product better?  Aside from
considering the doc as a part of the product and making *that* as good
as possible, how can we affect the structure, design and performance of
the products we describe?

We can make suggestions, certainly, and try to lobby developers and
engineers. I feel an obligation to do that. The product often improves
this way.

Sometimes, though, developers are too close to their products to view
constructive criticism with the correct perspective.  In this case, a
review draft describing the excruciating detail of an incipient
product's warts and defects, in cold, clear, clinically precise
language, can effectively expose the problems with a product as no
amount of constructive criticism can do. With luck (and a suggestion to
key developers to review specific sections of the doc "to make sure it's
absolutely accurate"), the review cycle results in overall improvements
to the product. Of course, you have to re-write your sections - but
that's sort of a small price to pay for a better overall product, no?

Glossing over the bad parts in review drafts hides the stuff in the
*product* that should change. Making nice words for bad things at this
point seems wrong. BUT, if exposing the faults of the product to your
internal reviewers does *not* cause the changes for which you had hoped,
maybe the final document can treat the flaws a little more gently for
your customers, while not sweeping anything under the rug. That seems
fair to me.

Besides, a customer buying something that the doc cheerfully promotes,
only to be disappointed by the reality of the product's performance, is
likely to feel misled. Reading about known problems in the doc, the same
customer is likely to feel that the company understands it's weaknesses,
warns it's customers about them in advance, and in so doing demonstrates
enough confidence in it's products *in spite* of the weaknesses to
inspire similar confidence in the customer. Wouldn't you rather know *in
advance* where the problems are likely to be, and then get advice on how
to avoid or minimize them?  I sure would.

I collaborated with another writer on a book about three years ago about
"programming tips" to improve performance using my company's software.
This is an excellent way to turn a product's negatives to your
advantage. The book sold very well, fostered good will among our
customers (who initially asked for it), and helped people use our
products better. I'm all in favor of that.

Ok, I've had my say. Thanks for listening.

|Len Olszewski, Technical Writer |"Thou gettest no bread with one     |
|saslpo -at- unx -dot- sas -dot- com|Cary, NC, USA| meatball." - Robert Sheckley       |
|---------------------------------------------------------------------|
| Opinions this ludicrous are mine. Reasonable opinions will cost you.|