Configurable On-Line Documentaton: Tools and Technologies?

Subject: Configurable On-Line Documentaton: Tools and Technologies?
From: Geoff Hart <ghart -at- videotron -dot- ca>
To: "TECHWR-L" <techwr-l -at- lists -dot- techwr-l -dot- com>
Date: Thu, 03 Mar 2005 09:34:07 -0500


Tony Rocco wonders: <<Does anyone on the list know of bibliographic and/or consulting resources that exist about authoring configurable on-line help?>>

Perhaps look into active server pages or similar technology? Basically something that submits a query to a database and dynamically builds a Web page in response? I only have the faintest notion of how this actually works, but perhaps others can provide more details. That being said, however:

<<I am documenting a leading-edge application with several licenseable modules and numerous configuration options. A client licenses different modules and configures different options based on their unique business requirements. The on-line help must automatically reflect the modules and options in use by a given client.>>

Let me play devil's advocate here: Why bother? Here's the way I look at this: If I don't own a module, I'm never going to consult the online help for that module, so why should I care if it's present? I may never even know that it's present. On the other hand, if I inadvertently stumble across such a module, and it seems interesting to me, I'll possibly buy that module so I can take advantage of its features. (This is known as "upselling" to marketeers.) If it doesn't interest me, I won't read about it.

So build one help system, structured so that it's context-sensitive, and don't worry about modularizing it.

If you're forced to modularize the help, it's easy enough to do: create a single help file for each module. I believe you can easily create cross-file links with all modern help tools, so cross-referencing won't cause any problems--so long as you ship all help files with the product to ensure that there are no broken links. Again, no reason not to do this.

<<It must also automatically configure itself to present particular levels of help based on user role.>>

Again, why? The simple, traditional approach is to present a single help page containing the information that all users need to know, with "more details" links below the summary information. Name these links based on the user's supposed role (e.g., "More details for administrators") and you achieve exactly the same effect elegantly and with no hassle.

I can imagine situations in which slobs like me shouldn't see the administrator-level help, but those are awfully rare: if I am not an administrator, I can't use the administrator's functions anyway, so knowing that they exist and being able to read the help describing them won't help me in any conceivable way. Odds are, I'm too busy to waste time exploring those features unless I'm able to use them.

If people must log in and out to take on specific roles, you can load the help files dynamically. For example, if someone logs in as "slob" (me), the software loads the slob help file; if they log in as "administrator", the software loads the admin help file. This is trivially easy to program--worst case scenario is that you create files called "Slob help" and "Admin help", and wire the program to load a file called "Module X help". Each time someone logs into Module X, the software opens the appropriate help file, renames it as "Module X help", and you continue onwards. (That's an inelegant, brute-force solution. I'm sure there are more elegant alternatives.)

<<In addition to this automatic configurability, it must be possible to output documentation for a given client-configuration to turn into training materials suited to that client.>>

As you've described this, it's an impossible task. What you're asking for is an artificial intelligence-based instructional designer, and they don't exist. What you can do is write training docs for each help module, probably using some variant of single-sourcing, and make those docs accessible at a single click. But instructional design is not yet something that can be automated. Some human needs to create the training goals, and design a training module that supports those goals.

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Geoff Hart ghart -at- videotron -dot- ca
(try geoffhart -at- mac -dot- com if you don't get a reply)
www.geoff-hart.com
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -


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

WEBWORKS FINALDRAFT - EDIT AND REVIEW, REDEFINED
Accelerate the document lifecycle with full online discussions and unique feedback-management capabilities. Unlimited, efficient reviews for Word
and FrameMaker authors. Live, online demo:
http://www.webworks.com/techwr-l

Doc-To-Help 7.5 Professional: New version with new features, improved performance and reliability, plus much more! Download your free trial today at www.componentone.com/techwrlfeb.

---
You are currently subscribed to techwr-l as:
archiver -at- techwr-l -dot- com
To unsubscribe send a blank email to leave-techwr-l-obscured -at- lists -dot- techwr-l -dot- com
Send administrative questions to lisa -at- techwr-l -dot- com -dot- Visit
http://www.techwr-l.com/techwhirl/ for more resources and info.



References:
Configurable On-Line Documentaton: Tools and Technologies: From: Tony Rocco

Previous by Author: Word temp files on networks? (Was: Document review process)
Next by Author: Configurable On-Line Documentaton: Tools and Technologies? (Take II)
Previous by Thread: Re: Configurable On-Line Documentation: Tools and Technologies
Next by Thread: Configurable On-Line Documentaton: Tools and Technologies? (Take II)


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


Sponsored Ads