RE: Business issues, documentation and editors

["Darren Barefoot" <darren -dot- barefoot -at- capeclear -dot- com>]

At my company, which deals in a brand new technology (Web Services),
this question of "why" has been particularly important. Not only is it a
concern because users may not be particularly familiar with this
technology, but also because it's basically an improved solution for
existing problems, so we need to answer the question "why shouldn't I
stick with what I've got".

We've got a fairly large doc set (maybe 800 pages?) for our flagship
product. To help address this "why" issue, I came up with a very svelte
little volume entitled "Concepts". It's saddle-stitched and just fifty
pages, and hopefully entices the reader before they get to the other,
massive tomes. This has lots of pictures and no procedures and just
describes what our product is and what problems it may solve. In short,
it tells a bit of a story. If anyone's interested, there are PDF
(http://www.capeclear.com/products/manuals/three/Concepts/pdf/cc3_concep
ts.pdf) and HTML
(http://www.capeclear.com/products/manuals/three/Concepts/html/)
versions available on the Web. If anyone's interested in Web Services
generally, I think this book gives a readable, half-decent introduction
to them as well.

This telling of a story is my point. I often give this advice about
writing white papers, which are often all about the "why". Telling a
story--describing in narrative terms how your product is solving a
problem--is an excellent way to address the "why". It may be as simple
as a few introductory paragraphs. However, ideally (and my "Concepts"
manual is not a good example of this), the story should run through the
entire doc set. This may mean using consistent and extended  examples
through the book(s), referring back to the introductory story or using
recurring visual elements to remind the user of the greater
problem/solution idea.

Hope that helps. Thanks. DB.



> -----Original Message-----
> From: bounce-techwr-l-65243 -at- lists -dot- raycomm -dot- com 
> [mailto:bounce-techwr-l-65243 -at- lists -dot- raycomm -dot- com] On Behalf Of 
> Steven Brown
> Sent: 10 January 2002 21:37
> To: TECHWR-L
> Subject: Re: Business issues, documentation and editors
> 
> What ideas do you have for incorporating the "why's"
> without distracting the user from the task at hand,
> especially in a very modular, online help environment?
> A few random thoughts:
> 
> - In online help, add a link at the top of topics
> titled, "why to use this feature," or "use this
> feature to simplify your workflow," or "making the
> most of Product_Name."
> 
> - Including the "why" into the introductory paragraph.
> 
> - For every feature/procedure, write a parallel topic
> that explains why or how it could be used. In online
> help, provide a link between each topic.
> 



^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Attention ForeHelp and Doc-to-Help Users! Upgrade your existing product to 
RoboHelp for FREE, through January 15th. RoboHelp can import your existing 
Help projects! Learn how else RoboHelp can benefit you. www.ehelp.com/techwr

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