Re: You Don't Need to Know How

[Janice Gelb <janiceg -at- marvin -dot- eng -dot- sun -dot- com>]

"Scott Browne" <sbbish -at- yahoo -dot- com> wrote:
>
>Andrew Plato <intrepid_es -at- yahoo -dot- com> wrote:
><snip>
>> 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. 
><snip>
>
> This is still part of knowing your audience - a point
> I think we all agree on.
>
> At my present company, our past documentation of our
> software was extremely in-depth and showed a great
> deal of product knowledge. If you could conceivably do
> it with our software or if it might affect 1 out of
> 1000 users, we documented it. We provided every
> possible bit of information about our software.[...] Our
> developers, architects, and integrators loved it. Our
> customers and users (the ones who actually paid for
> and used the software) hated it. They all said it was
> way too much information. They told us straight out
> that they wanted "Do A to get B" documentation. They
> didn't care how or why it worked, only what to do to
> make it work. We stripped down the documentation by
> about 75%. We took it to our customers (several of
> them), showed it to them, and asked their opinions.
> They loved it. They raved. 
>

Indeed. Unfortunately, many companies produce documentation 
that is more like a spec than a document intended to help 
the reader use the product. It's the difference between 
writing "The Joys of MyProduct" and "Using MyProduct." 

If your audience is going to do development with your 
product code, they need a spec. If they're going to 
be using the product, they need instructions on how 
to do so. Often, these are not the same sets of 
information.

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

*** 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.