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.
Subject:Planning modular help for software packages From:"Fugalli, Claudia" <cfugalli -at- csstars -dot- com> To:<techwr-l -at- lists -dot- techwr-l -dot- com> Date:Fri, 24 Feb 2006 10:14:13 -0600
Dear techwhirlers,
I need some advice about using conditional tags to create modular help.
Some background:
My company makes software for the insurance industry. For years these
products have evolved separately, but now they are all being
re-developed in .NET and will all share a common framework. All of the
products are web-based. Some of our clients host their data on their own
servers, and some use our ASP service.
This new combo software will have the following structure: 1) core
components, such as database and admin functionality, which all the
customers use; 2) five "packages," which are basically large sets of
features used by a particular market or industry; and 3) a whole bunch
of "plug-ins," which are small, specialized features that extend the
functionality of the various packages.
Our clients will be purchasing anywhere from 1 - 5 of these packages.
When the users log on, the appropriate packages and plug-ins will be
displayed, based on: 1) the packages that the customer purchased, and 2)
the security settings of the user. In other words, a customer who used
to log on separately to products A, B, and D will now have simultaneous
and seamless access to packages A,B, and D.
So far this is my plan for the online help:
1) Online help content written in RoboHelp X5 already exists for three
of the five packages. We are migrating to MadCap Flare soon, and I'm
considering at some point after that to merge all this content into one
big help file, so we don't have maintain separate versions of the same
core admin content. If you have tried something like this before, what
was your experience? Is it feasible only if the shared components remain
almost identical between packages? Is there some percentage of
functionality that has to be shared for this to be worthwhile?
2) I would like the structure of the help file to mimic the structure of
the product, so that if a customer didn't buy Package B then the help
for package B and its related plug-ins will be excluded from the help
file. (note that i only want to do this at the package level, not for
plug-ins -- people pay extra for those, and i'm hoping that the help
content can help sell them ;-).
3) I don't think it's feasible at this point to modularize the help
based on the security settings of the individual user (there would be
thousands of variations).
One of the existing help files covers two of the packages, and i've
already generated two versions of this help file using conditional tags.
My question is, this help file has about 1200 topics. if we merge all
the help files together, the total number of topics will be about 4,000,
and i'll have to generate 10-15 different versions of the help. At what
point are there too many output variations to be workable? And once you
hit that point, then what do you do? Will i have to climb out of my
well-worn RoboHelp hammock and learn some kind of java programming? ;-)
Eventually, what i would really like to do is deliver the help to the
developers in modular pieces, and then have these pieces get assembled
when the user accesses the help. In other words, i think it would be
cool if the system could see which package(s) have been deployed to the
user and then use that info to also deploy the appropriate help
components. Would I need heavy-duty programming skills to do this, or
are there tools available?
I'm subscribed to the digest, so please copy me on any replies.
If i get a bunch of responses i'll post a summary.
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
