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.
Kevin McGowan wondered: <<With our latest release, our product
introduced 5 different licenses, and the doc set is already suffering.
Due to some R&D confusion (and the fact that I'm now the only writer on
the team), the licenses are not clearly defined throughout the doc set.
If you have license A, you open the docs and you will see information
for license B, C, D, and E, even though it doesn't apply to you.>>
This shouldn't be a problem. Readers of our products are highly skilled
at ignoring information that directly concerns them, so I doubt they'll
be any less skilled at ignoring information that doesn't concern them.
<g> In terms of the licenses themselves, simply provide the license
information as a single help topic, with five subheadings, and start
that topic with a mini-TOC that lets them jump straight to the license
that relates to them. In effect, what you're doing is saying "if you
want to use the following features, you need to upgrade from license A
to license B (or whatever)".
<<I need to develop a help system that will allow me to simply
include/exclude information based on the license triggers in the UI.
And of course, I need to build it relatively quickly, because we've got
another big release coming up for January, and they're introducing at
least one more license option.>>
Similarly, don't bother trying to create multiple help systems. Create
a single system for all licenses. Most users will never see features
that don't relate to them because they'll be using context-sensitive
help; that makes the features that aren't relevant... irrelevant. <g>
To accomodate the needs of those who enter the documentation via the
index or search tool, and don't know that a specific feature isn't
available to them, simply add a note in each help topic about which
licenses it's available for. (Topics available for all licenses don't
need this disclaimer.) Think of this as a marketing tool: if you need
to be reading about this feature, you should be buying a license for
it. Where it's possible to accomplish something in multiple ways, state
which of those alternatives are available under each form of license
and what can be done if none of these solutions apply to your
particular license.
If you design your help system intelligently, the topic IDs won't
overlap, so you'll never have to worry about renumbering the IDs for
different licenses: each topic is identified with the same number in
all versions of the licensing.
WebWorks ePublisher Pro for Word features support for every major Help
format plus PDF, HTML and more. Flexible, precise, and efficient content
delivery. Try it today!. http://www.webworks.com/techwr-l
Doc-To-Help includes a one-click RoboHelp project converter. It's that easy. Watch the demo at http://www.DocToHelp.com/TechwrlList
