Re: Client access to edit Help

Subject: Re: Client access to edit Help
From: Robert Lauriston <robert -at- lauriston -dot- com>
To: "techwr-l -at- lists -dot- techwr-l -dot- com" <techwr-l -at- lists -dot- techwr-l -dot- com>
Date: Wed, 30 Mar 2016 09:58:46 -0700

Chris's tool isn't a product, it's something he developed himself.

On Wed, Mar 30, 2016 at 5:09 AM, Suzette Leeming
<suzette -dot- leeming -at- gmail -dot- com> wrote:
> 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

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

You are currently subscribed to TECHWR-L as archive -at- web -dot- techwr-l -dot- com -dot-

To unsubscribe send a blank email to
techwr-l-leave -at- lists -dot- techwr-l -dot- com


Send administrative questions to admin -at- techwr-l -dot- com -dot- Visit
http://www.techwhirl.com/email-discussion-groups/ for more resources and info.

Looking for articles on Technical Communications? Head over to our online magazine at http://techwhirl.com

Looking for the archived Techwr-l email discussions? Search our public email archives @ http://techwr-l.com/archives


References:
Re: Client access to edit Help: From: Chris Despopoulos
Re: Client access to edit Help: From: Suzette Leeming

Previous by Author: Re: For the love of spreadsheets
Next by Author: Re: Batch conversion of PDF to Word
Previous by Thread: Re: Client access to edit Help
Next by Thread: MS Office 2016


What this post helpful? Share it with friends and colleagues:


Sponsored Ads