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.
This is very similar to a challenge we are facing here. We produce
documentation for a large enterprise system with hundreds of different
configuration options. Clients want the online help to be customized for
their specific implementation, so that their users see help text that
matches the features available to them (rather than generic or universal
text that describes the features they might have access to depending on
how their system has been configured).
It seems to me the only solution would be to create a single universal
help system with conditional text that was interpreted at run time -- at
the point where an end user actually accessed the help system. So in
your case the complete help source for all OEMs would be deployed with
the software, then when the help system was accessed, the actual
information displayed would be filtered based on the particular OEM (a
parameter passed to the help system by the software).
I can't see an alternative if there is a single build process for all
OEMs.
The unfortunate part is that, as far as I can tell, all help authoring
tools are designed to filter the help output based on conditional text
at build time (i.e. when the help output is produced from the source
files), so that you end up building or publishing all the permutations
you need as separate outputs. I suppose you could bundle up *all* the
permutations into a single build, and have the software point to the
corresponding system based on the OEM -- but what you really need (and
what we really need) is to have an intelligent help system that filters
content down to the correct permutation at the point where an end user
accesses the system.
I'll watch this thread with interest in case others have simpler
suggestions, but it looks to me like the only way to accomplish this is
to create your own custom software for displaying help files to end
users.
Good luck,
Jeff Cross
-----Original Message-----
From: techwr-l-bounces+jeff -dot- cross=desire2learn -dot- com -at- lists -dot- techwr-l -dot- com
[mailto:techwr-l-bounces+jeff -dot- cross=desire2learn -dot- com -at- lists -dot- techwr-l -dot- com]
On Behalf Of David Loveless
Sent: Thursday, September 21, 2006 5:46 PM
To: techwr-l -at- lists -dot- techwr-l -dot- c
Subject: Help, Multiple OEMs, and the Build System
I'm creating help systems for several applications for several OEMs.
One application in particular is being especially nasty. This
application has three (potentially as many as 20) OEM-specific versions.
Each version has different branding and, in several cases, some
functionality changes. These changes are driven by the fact that the
application is being marketed to multiple audiences with multiple needs.
Each OEM wants Help Files specific to them that only deal with them and
no other OEM. Since these OEMs are often rivals competing for the same
market, it is absolutely vital that we comply and create customized Help
for each version.
The big problem we are having (and sorry if I'm not technical enough
here) is that our build system is designed to handle the main
application and the OEM-specific versions as a single application.
That includes the help. We cannot include multiple versions of the help
without creating multiple builds. That would require each build to be
built and tested independently of the other. Therefore, an increase of
one OEM build increases our building and testing workload by one. With
the potential of 20 OEM-specific versions, we could end up with 21
different builds and testing cyclese (20 OEMS plus the original
application). That is not an acceptable workload for our already
over-taxed Build and QA Team.
The question: Since a generic universal help is not an acceptable
alternative and multiple builds is not an acceptable alternative, does
anyone have any idea of how to handle this? We want/need customized
OEM-specific Help for each application.
One thought we had was to create an external website that users would go
to and then select their application from a list of available apps, but
only about 25% of our users connect their work machines to the internet.
Frankly, it seems that the answer is staring me in the face, but I can't
see it.
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
Easily create HTML or Microsoft Word content and convert to any popular Help file format or printed documentation. Learn more at http://www.DocToHelp.com/TechwrlList
---
You are currently subscribed to TECHWR-L as archive -at- infoinfocus -dot- com -dot-
