Re: Marketing/propaganda in documentation

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

Mike Beyries replies to the quandry of marketing stuff in doc:

> I have found it helpful to think of the marketing intro as a bridge
> between what the user was sold and what they have received.

Others have aired opinions ranging from "it depends", to "never do it",
to "always do it", to "do it, but be sneaky".

If you put it all in one spot, and it's all marketing stuff, and there
isn't any other marketing stuff in the rest of the doc, it seems to be a
bit *obvious*, don't you think?

While some potential customers might read the doc to help in deciding
whether to buy a product, it strikes me that they want to read the *doc*
to *get away* from the marketing literature. Presumably, the marketing
stuff "hooks" you, the sales people cream you, then you look at the doc
to see if the software will meet your needs from a technical
perspective. Seeing a hype chapter in a reference manual would impress
me about as much as paying seven bucks to see a movie and then sitting
through a bunch of commercials before the movie starts (it impresses me,
all right; it impresses me as crass, greedy money-grubbing).

Now, writing the doc itself with an eye towards making the product
appealing to specific audiences, there's a different kettle of fish
altogether. Using this technique, you coordinate with the marketing
folks to make sure that the characteristics of the audience who will be
buying the product are known to the writers (and also the developers),
who try to answer concerns or meet needs that particular market segments
express *in the doc*. This isn't empty hype; it's knowing your audience,
fullfilling your audience's needs and expectations, and by the way, it's
good marketing.

Being honest about the products shortcomings is ok, but not dwelling
there and emphasizing the strengths of a product are ok too. A good
marketing *strategy* is not just empty hype. This type of approach, done
successfully, *permeates* a manual. It just doesn't live in one chapter
at the front of the book, and in the long run, I think, is a more
successful method of injecting a marketing perspective into a book (and,
not incidentally, selling more of the product to the undecided - a
worthy goal, IMH capitalist O).

By all means, be marketing-oriented, but *think* about it a little.

|Len Olszewski, Technical Writer |"Never give anything a name that you|
|saslpo -at- unx -dot- sas -dot- com|Cary, NC, USA|might have to eat." -Klingon Proverb|
|---------------------------------------------------------------------|
| Opinions this ludicrous are mine. Reasonable opinions will cost you.|