Re: Planning modular help for software packages (summary)

["Fugalli, Claudia" <cfugalli -at- csstars -dot- com>]

Dear techwhirlers, 

Thank you so much for all your helpful replies, and sorry if my question
led to an argument. Actually I was a little afraid of that happening --
for some reason the modularization topic seems to be inherently
contentious. It's one of the only things that my coworker and I have
ever strongly disagreed about. I'm glad that we have a good working
relationship otherwise :-) 

Actually the whole thing kind of reminds me of the old war between the
lumpers and the splitters
(http://en.wikipedia.org/wiki/Lumpers_and_splitters). 

But anyway, below is a summary of the responses I received. Most of them
related to planning/analysis more than technical solutions. But that's
ok because I'm still in the planning phase, and I don't know enough
about XML yet to be able to process the more technical advice. If I were
totally honest I'd admit that I'm going overboard with the planning to
make up for my lack of technical expertise  ;-)  

Note: I'm using the term "modular help" to refer to a help file that
contains sections of content that can be easily excluded and still keep
the whole help file intact. Multiple versions of the help file can then
be compiled to accommodate customers that use different modules
(packages) in the application. 

These are the analytical issues that that got raised for planning
modular help: 
-- In the product, figure out which percentage of features are core
(common to every module), and which are specific to just one module.
Having a large percentage of core features would be a good argument for
merging the help files. 
-- Does the core functionality carry all the way through to the UI, or
will the UI be customized so that much of it will appear to be
module-specific? Technically this might be a modular application, but
the help content will probably vary so much that maintaining separate
help files might be the best solution. 
-- Does the help content need to be heavily linked, especially from the
core content to the peripheral content? A "yes" would support the
"include everything" option. If the peripheral content doesn't need to
be heavily linked to the other content, then maybe modularizing the help
is the better solution. 
-- Are the "packages" truly separate sets of functionality, or do they
represent shallow changes to a wide array of the app's features?
("installable modules" vs. "installable overlays," in the words of one
helpful respondent). Of our five packages, three are almost like
separate products, and two involve many shallow changes dispersed among
all the packages. 
-- This leads to another question: can you create modular help if the
product itself is not clearly modular? If I'm going to be compiling all
the different variations of the help files on my end, then the answer is
yes - I can apply conditional tags no matter how dispersed the modular
content is. However, if the help will be assembled when the user calls
it, then it would help if the modules were more separate entities. 
-- Are the modules recognizable as such by the users? Our "overlay"-type
modules are not recognizable as separate packages by most of our users. 
-- Someone also brought up the problem of upgrades. Boy, now that's
something to think about -- would all packages upgrade simultaneously
with the core functionality, or is everything on different schedules?
This question almost started a war in a developer meeting last week ;-)
Having different schedules would create a whole other layer of variables
in the help file plan. 

Based on the answers to these questions, I starting to think that the
solution is going to be a combination of separate help files for some of
the packages and modularizing the other ones. 

Several people suggested to give all the users all the documentation,
and just put extra work into the navigation. I like the "give 'em
everything" approach for several reasons, and not only because I'm lazy
;-)  Here are some good tips people offered to improve navigation in
non-modularized help files: 
-- Visually tag the package-level topics somehow, so people can quickly
see whether it pertains to them. (we already do this with admin-level
topics - they get their own special icon, so non-admin users can quickly
disregard them). 
-- Include frequent reminders that "some features may not be
supported..." (we already do this too, to cover all the variations due
to security settings) 
-- Include a "system options" section at the top of the relevant topics
that covers all the package-level variations within the procedure. 
-- Can also set package-dependent steps in expandable text. (One
drawback to this is that some people's browser settings always show all
the text expanded.) 
-- Content-sensitive links must be done well. 

Someone else reported that they have created a relatively complex
modular help file using Help and Manual, which can compile multiple help
projects as a single help file. (I'm not familiar with this product, and
we just purchased Flare, so I don't think we'll be switching HATs in the
near future.) 

I also came across these helpful resources: 

_Single Sourcing: Building Modular Documentation_, by Kurt Amend ((c)
2003, William Andrew Publishing)

http://jsp.davidcastro.com/index.jsp -- "JavaServer Pages for Web-based
Online Help"

http://www.rockley.com/articles/The%20Rockley%20Group%20-%20ECM%20UCS%20
Whitepaper%20-%20revised.pdf  --  "Managing Enterprise Content: A
Unified Content Strategy" ((c) 2003, The Rockley Group). There are more
useful whitepapers at www.rockley.com. 

http://www.writersua.com/articles/robohelp_ss/index.html -- "Tips and
Techniques for Single-sourcing with RoboHelp X5(r)," by Matthew Ellison
((c) 2005 WinWriters, Inc.) 

http://www.javaworld.com/javaworld/jw-04-1999/jw-04-xml.html -- "XML for
the Absolute Beginner," by Mark Johnson.

http://www.thecontentwrangler.com/ 


Thanks again for all your help!
-Claudia Fugalli 
cfugalli -at- csstars -dot- com



---------Original Message---------
Subject: Planning modular help for software packages


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. 

 

Thank you and have a great day --

-Claudia Fugalli 
cfugalli -at- csstars -dot- com

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

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.componentone.com/TECHWRL/DocToHelp2005

---
You are currently subscribed to TECHWR-L as archive -at- infoinfocus -dot- com -dot- 

To unsubscribe send a blank email to
techwr-l-unsubscribe -at- lists -dot- techwr-l -dot- com
or visit http://lists.techwr-l.com/mailman/options/techwr-l/archive%40infoinfocus.com

To subscribe, send a blank email to techwr-l-join -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.