Re: You Don't Need to Know How

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

--- chris anderson wrote:

> Let's not lose sight of the fact that technical writing is about
> communicating the "process" required to achieve a specific result and
> not
> about making users expert at the technology deployed that allows us to
> achieve a specific result .

That is not true in many cases. Just "achieving the desired result" is
what leads to overly simplistic documentation. This is fine for end-users
who demand extremely simple instructions with virtually no background. 

However, when dealing with complex technologies, many users are very savvy
and don't want to conform to the writer's well-ordered way of doing
things. They want the documentation to meet their needs - not the other
way around. 

Thus, the documentation must be much more savvy. It must educate the
reader rather than just instructing them to "achieve the desired result."
You must give the reader the basic information they need so they can make
their own decisions about the product and its usage. 

This is why so many documents are so bad. They assume EVERYBODY will use
the product the EXACT way it is documented. For many complex technologies
this is very rarely the case. This is what leads to frustration among
readers. They begin using a product in one way which works for them, Then
go to the documentation for additional information. Once they start
reading, it becomes immediately clear that the writer had no clue how the
product actually works. He/she was just regurgitating instructions handed
to him/her from an engineer and assuming there was only one "proper" way
to use the product. Thus, the documentation is totally worthless to the
user. 

This leads to support calls and unhappy customers.  

I can think of NUMEROUS product documents I have that are like this. Sure,
they tell me how to get A, B, and C tasks done. But that wasn't my
problem. I need to know WHY I need to do A, B, and C. And what does it all
really mean. I need to understand the product, not just be ordered around
by a writer who was more interested in "communicating the process" to me.
Process is fine, but without context, the process is meaningless.  

Let me put it another way - ignorance is more obvious than intelligence.
If you're ignorant about the product you're documenting, it will shine
through in glorious full-color stupidity in your documentation. You will
offend readers and turn off customers. However, if you know your products
very well, your expertise will make the material useful and meaningful -
leading to happy customers and less support calls. 

Andrew Plato 

__________________________________________________
Do You Yahoo!?
Make international calls for as low as $.04/minute with Yahoo! Messenger
http://phonecard.yahoo.com/

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

*** Deva(tm) Tools for Dreamweaver and Deva(tm) Search ***
Build Contents, Indexes, and Search for Web Sites and Help Systems
Available now at http://www.devahelp.com or info -at- devahelp -dot- com

Learn about tools and technologies for user assistance developers at
The Help Technology Conference, August 21-24 in Boston, MA
Details and online registration at http://www.SolutionsEvents.com


---
You are currently subscribed to techwr-l as: archive -at- raycomm -dot- com
To unsubscribe send a blank email to leave-techwr-l-obscured -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.