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:Suzette Leeming <suzette -dot- leeming -at- gmail -dot- com> To:Chris Despopoulos <despopoulos_chriss -at- yahoo -dot- com> Date:Wed, 30 Mar 2016 08:09:37 -0400
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
