TechWhirl (TECHWR-L) is a resource for technical writing and technical communications professionals of all experience levels and in all industries to share their experiences and acquire information.
For two decades, technical communicators have turned to TechWhirl to ask and answer questions about the always-changing world of technical communications, such as tools, skills, career paths, methodologies, and emerging industries. The TechWhirl Archives and magazine, created for, by and about technical writers, offer a wealth of knowledge to everyone with an interest in any aspect of technical communications.
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.
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.
