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:Re: Client access to edit Help From:Chris Despopoulos <despopoulos_chriss -at- yahoo -dot- com> To:Suzette Leeming <suzette -dot- leeming -at- gmail -dot- com> Date:Wed, 30 Mar 2016 12:30:23 +0000 (UTC)
I'm surprised that you can't look at the publishing output to see how the product generates your HTML files -- how it organizes them in directories, and how it builds the TOC. It seems your customers could just add a directory of custom content, and then add links to that in the TOC. If these are all just files that are stored in some location, I don't see the problem.Â
About DITA and smaller organizations... IMO it's a myth that DITA is for larger organizations. It all depends on how much you feel you need to spend to get it up and running. Since I'm the lone writer, I can do it all myself -- no need for expensive tools. And setting up the system I have has actually enabled me to produce more. I support about 50 engineers, create install, user, REST API, Java SDK guides -- plus relnotes, tooltips, and other GUI text. It would not be possible without the tooling I have, and DITA is a part of it.Â
But I digress...
CheersÂÂÂÂÂÂÂÂ cud
From: Suzette Leeming <suzette -dot- leeming -at- gmail -dot- com>
To: Chris Despopoulos <despopoulos_chriss -at- yahoo -dot- com>
Cc: "techwr-l -at- lists -dot- techwr-l -dot- com" <techwr-l -at- lists -dot- techwr-l -dot- com>
Sent: Wednesday, March 30, 2016 8:09 AM
Subject: Re: Client access to edit Help
I've been using an authoring tool called Help and Manual from EC Software, and single sourcing the in-browser help files and the PDF manuals; it's worked well for us. I looked at whether or not to switch to DITA, and was often told our company and documentation needs were too small for a DITA solution, which is preferred in larger organizations. Hence, I know very little about DITA. While we're currently able to add more topics to the help file, there isn't a way for our clients to compile the files to include their new topics in the TOC or index.Â
We don't compress our help files themselves; each topic is an html file. The best we're able to do is edit a topic to include a link to an external file. The product you're describing sounds like what we need. I've suggested the alternative of having our client purchase our help authoring software and we'll give them our source files. We never identified the need for localization. Customization, yes, but not localization. Â
Our help files are completely separate from our product - they sit in a separate directory and launch when help is called from within a module.Â
On Fri, Mar 25, 2016 at 7:53 AM, Chris Despopoulos <despopoulos_chriss -at- yahoo -dot- com> wrote:
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
