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.
Maintaining content between intranet site and CHM file
Subject:Maintaining content between intranet site and CHM file From:"Norcross, Amanda" <Amanda -dot- Norcross -at- kla-tencor -dot- com> To:<techwr-l -at- lists -dot- techwr-l -dot- com> Date:Thu, 24 Aug 2006 09:26:24 -0700
Hello fellow tech-whirlers,
I am trying to find the least cumbersome way to maintain duplicate
troubleshooting info between an intranet product web site and a .CHM
file that is generated from RoboHelp HTML X5 and sent out to customers.
The duplication is necessary because the web site offers a nice
on-the-fly method for posting the latest troubleshooting info for
internal field personnel, while the CHM file is THE documentation source
for our customers. The CHM file is released only once or twice a year
with the software releases. I need to figure out how to best keep the
information in synch, and I would like to hear your suggestions. My
project manager has suggested using the web site as the primary source
and simply taking a "snapshot" of the web site info before each software
release and putting that in the CHM file. I am okay with that idea but
not sure how to best execute it.
The web site is maintained by someone else. (I know less than squat
about web site design and technologies, so keep that in mind as you read
this post and offer suggestions.) I have been told by a third, web site
savvy person (not the web site designer) that the web site under the
covers is rather cobbled together right now and generally not done
properly. However, to the site designer's credit, he *has* made an
admirable effort in creating and maintaining the site, even if the
execution is not ideal. The content is entirely maintained in text
files. He is using Tomcat, which is a JSP server. He uses JSP to track
user downloads and other info. Everything else is HTML. The plan is to
move to SharePoint. I have no idea whether that's a good move or not;
regardless, I can't count on the move happening anytime soon. Keep in
mind that none of these are my decisions, which is essentially fine with
me. Web site technologies are not an interest of mine. However, I will
be working with the designer to establish a baseline for the
troubleshooting content of the site and I will play a significant role
in working with him to maintain the info, primarily reviewing/editing
new content and giving him feedback.
As for the CHM file, RoboHELP is the product and that's not going to
The amount of troubleshooting info is approximately 30 pages or so. I
expect that to grow at a moderate rate as time goes on.
The biggest challenge is that the content is not going to be identical.
Specifically, the CHM file will contain hyperlinks that the web site
will not contain. Also, about 10% of the web site content will not be
duplicated in the CHM file.
Possible Synching Methods
So this is where I need your help. The only ideas I've had are pretty
primitive. Copy/paste is an option, though it doesn't seem like the best
one. One, it's cumbersome and two, I loathe the idea of reformatting and
relinking content in RoboHelp before every software release. Comparing
the two sets of info side-by-side sounds like a nightmare, especially as
the content grows, and I am likely to overlook subtle differences. I
know there must be other options that are more robust and more
efficient, but I just don't know what they are. Is single-sourcing an
option, given the tool set and constraints? I am not knowledgeable about
single-sourcing, so there could easily be solutions in that area that I
am unaware of. Anything other ideas?