Including very complex explanation in a simple document

[John Posada <jposada01 -at- yahoo -dot- com>]

Hi, guys...I'm having a discussion with one of the development
managers. BTW...the answer to my question isn't to rewrite the
application, though it may be the best solution.

I'm documenting an application that is contains screens and tabbed
dialogs to configure a very large portal.

Part of one of these dialogs is to document how to configure Web
Services for some portal pages. As background, while it is not the
right kind of web service, an example of a web service is something
like a stock quote service in the middle of a web page. Think of "My
Yahoo" as a page full of web services.

Anyway...part of the configuration is to design one or more XSLTs for
defining how the web service data is displayed on the web page.
XSLTs, while second nature to some of you, can be quite intimidating
if you don't know how to define them.

So...the discussion is how to get our less knowledgeable users
through the complete configuration process, which includes creating
XSLTs. A saving factor is that most web service providers present the
code that must be transformed in a pretty standard way...almost 

The developer's approach is pretty much point them to some learning
resources and leave them on their own. My approach is to attempt to
present a few basic examples and then explain what they need to do to
what, to get certain results. The idea being that they don't need to
know why they are doing something, just that they need to do it.

Has anyone ever had success getting a reader through a sticky part of
a configuration by gettng them to follow by example rather than
becuase they know what they arfre doing? I don't have constraints on
how much documentation this should consume...it could be a page or it
could be a chapter.

Anyone gone through this before?

John Posada
Senior Technical Writer

"Bigamy is having one wife 
 too many. Monogamy is the same."
     --Oscar Wilde
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Now Shipping -- WebWorks ePublisher Pro for Word! Easily create online
Help. And online anything else. Redesigned interface with a new
project-based workflow. Try it today! http://www.webworks.com/techwr-l

Doc-To-Help 2005 now has RoboHelp Converter and HTML Source: Author 
content and configure Help in MS Word or any HTML editor. No 
proprietary editor! *August release. http://www.componentone.com/TECHWRL/DocToHelp2005

---
You are currently subscribed to TECHWR-L as archive -at- infoinfocus -dot- com -dot- 

To unsubscribe send a blank email to 
techwr-l-unsubscribe -at- lists -dot- techwr-l -dot- com
or visit http://lists.techwr-l.com/mailman/options/techwr-l/archive%40infoinfocus.com

Send administrative questions to lisa -at- techwr-l -dot- com -dot-  Visit
http://www.techwr-l.com/techwhirl/ for more resources and info.