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.
Your product sounds very similar to the user interface for one of our major
products. We provide a form-based browser interface for content authoring,
with a Help file that describes common content author activities (for
instance, searching for content). But we don't document any specific
interface because they are intended to be customized.
Our position has been that, while it is desirable to provide help for these
customized editors, it is simply impractical. Instead, we are migrating to
JavaHelp, which uses separate XML files to provide the table of contents
and the index. We will provide basic guidance to the implementer about how
to write Help topics, as well as how to include them in the Helpset.
Eventually, we'd like to build this into the product itself, but that's
some time down the road yet.
We have not yet completed this conversion, but I'd be willing to discuss
what we've done so far and what we're planning on doing in the future.
I'd also be interested in hearing about other approaches to this problem.
I have become involved in a project creating a highly customizable
content editor ("authoring environment"--how's that for
marketing-speak), and part of what we want client developers/customizers
to be able to customize is the online Help. The editor and its core Help
file as shipped will be extremely basic, but customizers/developers will
be able to create an end-use editor as simple or as complex as required
for their situation or organization, complete with forms, dialog boxes,
and menu commands that we would never have foreseen.
Currently, we provide online Help in HTML (.chm) format with our
products, and have in the past included brief instructions for using MS
HTML Help Workshop to create a customized help file and merge it with
our help file. This, however, can be a pretty unwieldy process for the
average non-tech-writer to have to navigate alone--so much so that most
customizers and developers haven't bothered to customize the help,
leaving the end-use authors with little or no help using the product as
customized. For this reason, we are hoping to find some format or tool
that we can use to create truly customizable online Help, where
customizers can add their own topics with a minimum of fuss. (Being able
to annotate existing help topics or change the names of fields would not
go far enough--we need client developers to be able to create entire
topics and sub-topics.)
Has anyone on the list worked on a similar project in the past? If so,
how did you address this issue? I would appreciate any tips or guidance
you can provide.
Lorraine L. Butchart
phone: (604) 430-1966 Ext 4429
e-mail: Lorraine -dot- Butchart -at- corel -dot- com
Absolutely FREE! FrameMaker/Win 6 & 7 Express Customization (v3):
Quick-access buttons & keys to common functions, char tag/font drop-down
lists, charset browser, QRef guides & much more: http://www.microtype.com/2
Experience RoboHelp X3! This new RoboHelp release combines single sourcing,
print-quality documentation, conditional text and much more, into the most
monumental release of RoboHelp ever! http://www.ehelp.com/techwr-l
You are currently subscribed to techwr-l as:
archive -at- raycomm -dot- com
To unsubscribe send a blank email to leave-techwr-l-obscured -at- lists -dot- raycomm -dot- com
Send administrative questions to ejray -at- raycomm -dot- com -dot- Visit http://www.raycomm.com/techwhirl/ for more resources and info.