RE: Including very complex explanation in a simple document

["James Jones" <doc-x -at- earthlink -dot- net>]

How about structuring your documentation so that it has, somehow, (1)
specific steps that clearly explain what users are supposed to actually do
to attain their goals, and (2) a section after each of those offering an
optional explanation. This kind of 'what - why' documentation is quite
effective I believe.

The optional reading for explanation sections should not repeat the
instructions but should refer to them of course.

Jim Jones http://www.tinyurl.com/4arjc

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


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

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.