Including very complex explanation in a simple document

Subject: Including very complex explanation in a simple document
From: John Posada <jposada01 -at- yahoo -dot- com>
To: "List,Techwriter" <techwr-l -at- lists -dot- techwr-l -dot- com>
Date: Thu, 15 Dec 2005 11:36:42 -0800 (PST)

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

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.

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

Send administrative questions to lisa -at- techwr-l -dot- com -dot- Visit for more resources and info.


Previous by Author: Re: The more you know, the less you know you know?
Next by Author: takes me three hours to get in this morning...
Previous by Thread: RE: CLP Converter
Next by Thread: RE: Including very complex explanation in a simple document

What this post helpful? Share it with friends and colleagues:

Sponsored Ads

Sponsored Ads