Re: Simplicity

["Tim Altom" <taltom -at- simplywritten -dot- com>]

I don't accept the assertion that manuals are so ephemeral that they are
good for only one or two passes for a given user. If that were so, manuals
could be printed on newsprint and bound with paper clips.

The number of "openings" for any given manual depend on a great many
factors, such as the complexity of the subject matter, the familiarity of
the users with the product, the longevity of their employment, and, of
perhaps the greatest importance, the quality of the manual. Or, perhaps I
should say more explicitly, the *usefulness* of the manual...how well it
meets users' needs. In my experience, manuals gather dust most often when
they're badly written or out of date. Turnover in most companies is so high
nowadays that the average user may have only a few months working with any
given product. In fact, I've seen manuals that are still being used that
were written in the 1970s. That seems to me to qualify for a quality target
of 24/7; few roofs have lasted so long.

Undoubtedly there are tragically anal-retentive writers who agonize for so
long over trivial matters that they don't get much done. In every business
there are those who wind up interminably, but never release the ball. It's
also true that there's a point of diminishing returns, where the final 10%
of quality perfection consumes 90% of the money.

I'm not sure what you mean by "simplicity". Presumably that means "the
absence of the extraneous", but what in any given case IS extraneous? Does
that mean steps without long explanations? Or good page numbering?

My major argument is that our industry needs a set of best practices to help
untangle the spilled spaghetti bowl we have now of guesswork, spotty
experience, and hunches. We can minimize our stupidities by reading,
absorbing, and using the research that we now have access to. Few writers
bother. I find that unfortunate.

Too, remember that the emphasis on process and regularity is primarily an
artifact of a company's maturity. Small startups are lucky to survive, and
often overlook the finer points of communication. We may forgive them a
little myopia. I find the same trait less understandable in companies that
know better, that institute and enforce quality standards in the products,
but not in their documentation.

Tim Altom
Simply Written, Inc.
Featuring FrameMaker and the Clustar Method(TM)
"Better communication is a service to mankind."
317.562.9298
Check our Web site for the upcoming Clustar class info
http://www.simplywritten.com


> However, this metaphor breaks down when we consider one crucial point
about
> documentation: it is rarely used more than once. Documents are often read
once
> and then thrown on a shelf to collect dust.  Many are barely read at all,
> consulted only when info is needed.
>
> A roof needs to fulfill its purpose 24/7. A document only needs to fulfill
a
> purpose once or twice to a given reader.
>
> Therefore, it is not always fiscally prudent for corporations to spend a
> gajillion dollars on hiring tech writers to sit around all day dreaming up
> rock-solid documentation processes and designs. Yes, it FEELS like the
right
> thing to do, but you must remember that just because something FEELS right
to
> do, does not mean it is the BEST thing to do.
>
> Naturally, organization, layout, and a clean style contribute to
readability
> and usefulness.  Nobody will disagree with this. However, there is a limit
to
> these issues and the limit is a lot lower than many tech writers seem
willing
> to accept. It is nonsense to have a layout or a style that interfears in
anyway
> with the efficient production of manuals. Just as it is nonsense to have
tech
> writers who do not write.
>
> Simplicity is one of the most powerful persuasive models. When I am
reading a
> document I want simple, clean information. I want descriptions that
explain
> things in clear, unambiguous language. I don't care about the font, the
colors,
> or the size of bullets. Quite honestly, I don't even care about the
grammar.
>
> Tech writing is not an exercise in English, journalism, or personal
expression.
> It is teaching. You must teach readers about a topic. How many of us would
> attend a class where the professor spent all day telling you about his/her
> seating chart? Its pretty annoying (and a total waste of time) to take
lessons
> from a person who does not understand the topic.
>
> If you want to teach, you must A) know the subject matter B) understand
how to
> teach effectively.  To write effectively, you cannot have B without A,
however
> you can have A without B.
>
> Andrew Plato
> __________________________________________________
> Do You Yahoo!?
> Talk to your friends online with Yahoo! Messenger.
> http://im.yahoo.com
>
> ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
> Sponsored by Weisner Associates Inc., Online Information Services
> Training & consulting for RoboHELP, Dreamweaver, HTML, and HTML-Based
Help.
> More info at http://www.weisner.com/train/ or mailto:training -at- weisner -dot- com -dot- 
>
> Your web site in 32 languages? Maybe not now, but sooner than you think.
> Contact ForeignExchange for the FREE paper, "3 steps to successful
> translation management" (http://www.fxtrans.com/3steps.html?tw).
>
> ---
> You are currently subscribed to techwr-l as: taltom -at- SIMPLYWRITTEN -dot- COM
> To unsubscribe send a blank email to
leave-techwr-l-9923A -at- lists -dot- raycomm -dot- com
> Send administrative questions to ejray -at- raycomm -dot- com -dot-  Visit
> http://www.raycomm.com/techwhirl/ for more resources and info.