Simplicity

[Andrew Plato <intrepid_es -at- yahoo -dot- com>]

Lots of ideas on this topic. Fun topic too.

However, I think a few ideas are getting overused and bent out of shape.

Yes, our profession is very much like a roofer. We must produce a product and
that product is (hopefully) useful.  And as Tim Altom pointed out, roofers come
in many different flavors.  Some are experienced masters that may take a little
longer but produce top quality product. Some are entry level journeymen who can
do the job, but leave some flaws. Others are novices who would probably blow up
your house.

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