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 exactly what we do -- in-browser help served up by the customer's installation of our product (a server on a VM). Yes, there are reasons to do this, and in fact, I believe it's a preferable paradigm -- distributed dynamic doc display... Don't get me started.
Because our product is a server, we took advantage and came up with our own implementation of a single page app that displays the help topics. The topics are installed as raw DITA, and the help system transforms the DITA to HTML on the fly. This makes it very easy to add in more topics, or to filter the existing ones. Change the DitaMap to update the TOC, and add the topics into the content directory.
Because this is our own help server, we can get content from anywhere. Our product supports customers making remotely served additions to our features. So you can create some features, serve them from another component on your network (or outside of it), and the product integrates that into the GUI. The docs for such a feature should live with the feature itself... And so they do. Our help app loads the remote ditamap and stitches it into the existing TOC. Then calls from those new TOC entries can load in the remote topics.Â
We're also able to integrate other types of content. Even though the help s distributed with the product, we can integrate with a centralized comment center, for example. Any customers with open access to the net can use that feature. We're working on it, and should deliver that in a quarter or two.
I'm not sure why you need to compress the help files -- what do you gain? It would be interesting to know more about that (if you're free to share). I wonder if you could deliver a help SDK, where you give the original source files as HTML, include the compiler, and then the customer can change the source and compile it into a new system.Â
Alternatively, you could implement a way to stitch in arbitrary custom content, where you pick up the custom files from a known location on your server. Then as you build the TOC, you check for new TOC entries and pick them up. You could also implement some way to append content to each topic on the fly... Similar to a comment system. But all this assumes you have that kind of control over your help application.
If the help is overly integrated in the compiled product itself, I'd suggest moving away from that... It's better to load help content from an external repository of some sort. Otherwise, how do you deliver localized versions of help? Anyway, the more separated your help source is, the easier it is to implement and deliver these types of solutions... IMO.
-----Original Message-----
Background:
We deliver browser based help files for our enterprise software but it`s
installed on our clients' servers for security reasons (let`s not debate
that).
Our clients want the ability to "modify" the help files so that it can
include their own internal process information and links to their internal
documents as well.
This has been fairly straight forward in the past and all they required was
an html editor because we deliver the help in an uncompressed format.
We now have much more complex help files and it`s not straight forward
anymore and some clients may have an issue with this, and it`s become a bit
of an internal thorn in my side. Indeed, many of the RFPs we respond to
specifically ask "can the help files be modified?"
My question to the group is this; is anyone else in the same situation and
if so, how do you handle it?
Suzette Leeming
PS - My most recent suggestion was to give clients our source files and
suggest they buy a license to the help authoring tool we use. That
suggestion did not go over very well.
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Visit TechWhirl for the latest on content technology, content strategy and content development | http://techwhirl.com
