23 Replies Latest reply on May 13, 2008 10:00 AM by HKabaker

    Output format question

    MSCaroline
      The software company I work for has historically provided locally installed compiled help files for our products, but is considering changing to server-based help. We'd still like to provide a local help file for times when the user is offline, though, and this is where I'm running into some trouble. We've been using *.chm files, but nobody seems to like the look of them very much. It's my understanding that their appearance can't really be customized much, so I've been looking toward using locally installed WebHelp or FlashHelp. I've encountered tremendous resistance from the developers, though, and not for the size-related reasons I expected. Rather, they say that when they build an installation, they must specify each and every file that has changed. I can't really speak to their process, but if this is accurate, I can see how an uncompiled format would be daunting!

      So I'm looking for any sort of feedback that anyone can provide. Has anyone ever run into this particular objection? I've certainly not heard of it in these forums before. Does anyone have any suggestions on potential ways around this? Am I missing some compiled help format that I should know about? Has anyone had any experience packaging WebHelp output into some single file, such as perhaps a self-extracting zip archive or ...? Any suggestions would be greatly appreciated.

      Thanks,
      Melinda
        • 1. Re: Output format question
          Captiv8r Adobe Community Professional & MVP
          Hi Melinda

          You are probably going to be very interested in the RoboHelp packager for Adobe AIR! Basically, this application allows you to create WebHelp output, then use the packager to create a single package that is installed on the end user's PC.

          You may see more about this application by clicking here.

          Cheers... Rick
          • 2. Re: Output format question
            Peter Grainge Adobe Community Professional (Moderator)
            If your help includes any links to PDF files, then a downside of locally installed webhelp is that those links will not work.

            I think you need to get to the bottom of why the developers need to specify every file that has changed. There a various DIFF applications that identify the differences between the contents of one folder and another including sub folders. You could use one of those to provide the information required. I have not seen anyone request this information before.

            AIR help could be a solution longer term but it is still in beta and at the moment it can only be installed locally and cannot be called from an application. The server version is not yet available, even in beta. You also need to be aware that the single AIR file is not the help itself. It is an installer that effectively "unzips" your help to the right location. What it does is install a program that becomes the help. Longer term I think AIR help will be big. It has some nice features for end users such as Favourites and Comments where they can add their own notes. It was shown at the WritersUA conference and generated a lot of interest.

            You are looking for something that can be on a server when available or local when not.

            - Local webhelp and server webhelp would require some work from your developers to sniff whether a connection is available and divert the call to the right location. It also has the PDF issue.

            - Local CHM and server webhelp would require even more work from your developers. As well as sniffing the availability of a connection, they would have to make different calls to the local help. If you generate merged help, you too would need to redo all your links.

            - AIR may well be the solution longer term. If you want to look at it, there's an article on my site about setting it up. It does not affect your RoboHelp installation or your source files so you can try it out easily.

            • 3. Re: Output format question
              Peter Grainge Adobe Community Professional (Moderator)
              I omitted to mention a key benefit that will appeal to your developers. The same output will run on Windows, Unix and Macs. It is browser independent so no Internet Explorer / Firefox issues. That should make them listen.

              • 4. Re: Output format question
                HKabaker Level 2
                Peter,

                Please explain more about links to pdf files not working for locally installed WebHelp.

                I keep a master copy of all output files on my hard drive. Pdf files are linked from the TOC as well as from text links in topics.

                The link opens the default reader for pdf files, which was Adobe Reader for a long time. More recently, I also have Acrobat installed.

                Are you saying that locally stored WebHelp will not open pdf files if you don't have Acrobat on the hard drive? Or are you referring to pdf files stored only on the network?

                Thanks

                Harvey
                • 5. Re: Output format question
                  HKabaker Level 2
                  Melinda,

                  When you say you want users to have off-line access, that can mean a couple of things.

                  1. The application is not running on the user's PC, and the user cannot connect to the Intra/Internet location. Here, off-line means the user's browser can't get to the Intra/Internet.

                  2. The application is not running on the PC, but the user can connect to the WebHelp location. To some people, off-line means just that the application isn't running, but a browser can get to another Intra/Internet location to open the help files independently.

                  For case 2, a couple of possibilities:

                  1. If the WebHelp launch page doesn't have an Intra/Internet URL, perhaps the developers can arrange to have one assigned. The user then can go directly to the help system without running the parent application.

                  2. Get a separate server location for a copy of the WebHelp files. Have an URL assigned to it, and let users mark it for "off-line" reading.

                  Of course, you must to be sure to install WebHelp updates in both places.


                  3. Store a copy of WebHelp on a Network hard drive for access via the directorypath/filename system. I do not recommend this, because nowadays network communications to the PC have more authentication/verification roadblocks than browser/url traffic. I don't know the technical details, but imagine a gatekeeper between the PC and every link request (network traffic), compared with a password secured login for the first connection only (Web).

                  I hope someone with deeper knowledge of the subject will chime in here and verify or correct my explanation.

                  Harvey
                  • 6. Re: Output format question
                    Peter Grainge Adobe Community Professional (Moderator)
                    Harvey
                    quote:

                    Are you saying that locally stored WebHelp will not open pdf files if you don't have Acrobat on the hard drive? Or are you referring to pdf files stored only on the network?

                    No. I am saying that people have reported the links in topics do not work locally. Guess I need to test it.

                    • 7. Re: Output format question
                      Linux Rules Level 2
                      quote:

                      Originally posted by: MSCaroline
                      ...Rather, they say that when they build an installation, they must specify each and every file that has changed. I can't really speak to their process, but if this is accurate, I can see how an uncompiled format would be daunting!

                      Has anyone ever run into this particular objection? ... Has anyone had any experience packaging WebHelp output into some single file, such as perhaps a self-extracting zip archive or ...?


                      Hello Melinda -

                      Yes, been there and tackled that. One solution I used was to "agree" that the entire Help module would be treated as a whole. Help has an "About" page that lists the generation date and notes on major revisions. The Help is zipped as a single file for the Build Manager and I inform the manager of the generation date to include in the Build Notes.

                      As to other formats, please be painfully aware of your current and near-term customers needs, requirements and especially their restrictions. I can not use Flash, will not even load the viewer to my government workstation, and since the new AIR uses embedded Flash, will not use AIR either.

                      For some, security is much more important than the use of a single tool or software product.

                      Regards,
                      GEWB
                      • 8. Re: Output format question
                        HKabaker Level 2
                        Unless you find a way to make Adobe Air work for you, I agree with GEWB that you should try to get the developers to agree that one zip file replaces everything. When they deploy the application, they can explode the zip file into the appropriate directories.

                        Otherwise, you have to tell them which files changed; which are obsolete, to be deleted; and which are brand new and don't replace older ones.

                        There are some file comparison utilities. One I use a lot is called Beyond Compare. It's inexpensive and very powerful.

                        Working with the WebHelp output package, you can compare the new set against the old one and generate a report, if all you need is a list of changes. The application also can mirror or sync one set against the other, so you don't have to move files manually.

                        You can fine-tune the comparison criteria. When the filenames match, do you want to replace the old one if the dates/times are different? Or, if the files otherwise are exactly the same, leave the old one alone? Doing the latter can save a lot of housekeeping and file transfer time.

                        Good luck.


                        Harvey
                        • 9. Re: Output format question
                          HKabaker Level 2
                          Duplicate post.
                          • 10. Re: Output format question
                            HKabaker Level 2
                            Duplicate post.
                            • 11. Re: Output format question
                              MSCaroline Level 1
                              Thanks to all for so many thoughtful replies. I've been kind of sitting quietly and listening, thinking how great a resource these forums are.

                              Harvey raises a valid point-- my question could be understood a number of ways. To be specific: our applications are, mostly, installed on the individual user's machine. When I say "offline," I mean that the user doesn't currently have an Internet connection.

                              I think Peter is correct in his assessment that AIR, while promising for the future, is not quite yet a workable solution. I'm having some limited success in selling the idea of zipping the output and treating it as a single entity. The concern on that point seems to be that if the files are installed via an unzip, our software installer is essentially "unaware" of them as a component of the installation, which leads to questions about how they will be removed in the case of an uninstall. Thoughts?

                              A side note: GEWB, I'm interested by your comments about Flash. Is it common for companies/organizations to forbid or frown on its use? I actually am still making a decision between WebHelp and FlashHelp, so this could be very useful information for me.

                              Thanks,
                              Melinda
                              • 12. Re: Output format question
                                Peter Grainge Adobe Community Professional (Moderator)
                                It might be altogether better if your developers trashed the help each time and reinstalled it complete. Sounds like your routine might not remove files that are no longer required.

                                The install and uninstall is a developer issue.

                                • 13. Re: Output format question
                                  Linux Rules Level 2
                                  quote:

                                  Originally posted by: MSCaroline
                                  A side note: GEWB, I'm interested by your comments about Flash. Is it common for companies/organizations to forbid or frown on its use? I actually am still making a decision between WebHelp and FlashHelp, so this could be very useful information for me.



                                  Hello Melinda -

                                  Restricting Flash or other such things is NOT common unless working in "sensitive" areas. Some "non-sensitive" companies are placing restrictions on Web sites AND the Flash format due to employee abuse of sites such as YouTube.

                                  If you do a search you will find that Flash has a history of exploits, bugs, etc. (there was yet another major Flash problem just last month) - not as bad as Microsoft Internet Explorer but bad enough that some IT departments are tired of dealing with it. Sadly this is the exception, not the rule. Therefore, many companies and individuals still allow the use of IE and Flash so you probably will not have a problem - until there is another major exploit and sys admins start to clamp down.

                                  Regards,
                                  GEWB
                                  • 14. Re: Output format question
                                    HKabaker Level 2
                                    Melinda,
                                    quote:
                                    ... Our applications are, mostly, installed on the individual user's machine. When I say "offline," I mean that the user doesn't currently have an Internet connection.
                                    ----------------------------------------------------------------------------

                                    You have the application and help files on the local machine, and the developers want to move just the help system, is that correct?

                                    What benefit do they have in mind? Do you frequently update the help system between releases of the application? Are they just trying to separate the two installations?

                                    If this is being driven by their need to know which files changed, you or they can generate a Delta report between the current version and the new one.

                                    Harvey
                                    • 15. Re: Output format question
                                      MSCaroline Level 1
                                      Harvey asked:

                                      quote:


                                      You have the application and help files on the local machine, and the developers want to move just the help system, is that correct?

                                      What benefit do they have in mind? Do you frequently update the help system between releases of the application? Are they just trying to separate the two installations?


                                      Well, the main goal is to start using WebHelp Pro, thereby gaining the feedback that it's capable of providing and, yes, allowing us to continuously improve the help based on that feedback. I'm afraid that I was the one to open this can of worms for that reason. As for the local help files, I think what it came down to was that folks really hate the look of the chm, and since we're shuffling things around anyway this was perceived as an opportunity to move away from chm. I think people probably didn't realize that there aren't many options for compiled help files... so here we are.

                                      Peter, I think you're right that the entire help system should be trashed and replaced or, in the case of a full uninstall, simply trashed. I gather that this will involve writing some extra code to deal with that, since the unzipped files aren't technically part of the installation. Not impossible, by any means, but it's been a bit difficult to get buy-in. When I met with these folks yesterday, though, they were at least seriously considering how to do it, which says to me that they understand how this could be worthwhile, so that's encouraging.

                                      GEWB, thanks for the info. Our customers are from an extremely wide variety of industries and I wouldn't be at all surprised if some do restrict Flash. Sounds like WebHelp is the way to go.

                                      Thanks,
                                      Melinda
                                      • 16. Re: Output format question
                                        MergeThis Level 4
                                        Usage reports in WebHelp Pro projects only apply to WebHelp Pro projects that reside on a RoboEngine server. That is, a RoboEngine server that you control; not output files on your customer's servers or local machines. Although I haven't used this output myself, it seems that other postings confirm that assumption. Any experts confirm or deny?


                                        Good luck,
                                        Leon
                                        • 17. Re: Output format question
                                          RoboColum(n) Level 5
                                          Hi Leon.

                                          Far from being a RoboServer expert - I've only dabbled with the product and not as yet used it in anger - you are correct. The reports use the data gathered from users accessing the help on the RoboServer itself.
                                          • 18. Re: Output format question
                                            MergeThis Level 4
                                            The resolution appears to be quite simple, as it is in our environment.

                                            When you generate WebHelp, you generate all the output files to a location on your local machine (RH calls it updating).

                                            When you then publish WebHelp to locations on the server, RH only replaces the changed/added files (we publish to two directories, one for internal review and the other for release engineering to sweep up into the product that gets shipped). Your IT folks could certainly pull in only those files with certain date stamps, but why bother? Just pull in all the files and there's never a missing-file issue.

                                            It should not be any more difficult than that, unless there are some in your organization who insist that their way is the only correct way, in spite of overwhelming evidence to the contrary. Sigh...


                                            Good luck,
                                            Leon
                                            • 19. Re: Output format question
                                              Pet3689 Level 1
                                              We have been struggling with these ideas for quite some time now.

                                              For our installed application, we use HTMLHelp. However, we would like to switch to something more "flexible". WebHelp and FlashHelp come to mind. The main disadvantage of WebHelp is that the help appears in the user's web browser (which could be "exotic"), which may be cluttered with distracting GUI add-ons. FlashHelp is cleaner, but requires installation of Flash. Both have the disadvantage of multiple files and folders. The latter problem bothers our developers a lot, for installation/update/uninstallation reasons.

                                              The solution with the single ZIP file is genius. I have no idea why we never thought of this ourselves. Dumb dumb dumb.

                                              Conceptually, a ZIP file works really well for a clean install. For uninstalling, you just have to delete the folder that the ZIP file was extracted into. No need to keep track of the individual files and folders. When replacing just a few files (i.e., update), we can just ZIP the modified files, and that should take care of it.

                                              Are we missing something, or is a ZIP file indeed a wonderful solution for the scenario of installing an application with WinHelp or FlashHelp?

                                              In fact, I am at a complete loss why the FlashHelp format uses all of these files and folders, instead of a compressed (ZIP-like) file (like CHM) instead. We have used Captivate 2 to create Flash, and this always resulted in a single file. Of course, these were probably Flash animations, and FlashHelp seems to be different (i.e., no time/progress slider). Of course, AIR address this problem, but why did we have to wait until 2008 for this improvement!?

                                              Thank you so very much, dear forum members, for your valuable suggestions!!!
                                              • 20. Re: Output format question
                                                RoboColum(n) Level 5
                                                Why not just publish your webhelp / flashelp output to a server or website and point the application there? This is what it is designed to be used for. If stored locally, CHMs are best. What is it you want to achieve from your more flexible approach that a CHM can't provide?
                                                • 21. Re: Output format question
                                                  HKabaker Level 2
                                                  Pet wrote:
                                                  ---------------------------------------------------------------------------
                                                  Conceptually, a ZIP file works really well for a clean install. For uninstalling, you just have to delete the folder that the ZIP file was extracted into. No need to keep track of the individual files and folders.
                                                  -----------------------------------------------------------

                                                  So far, so good. But then:

                                                  --------------------------------------------------------
                                                  When replacing just a few files (i.e., update), we can just ZIP the modified files, and that should take care of it.
                                                  --------------------------------------------------------

                                                  Now we're moving back toward keeping track of individual files, whether they were modified or not modified.

                                                  For all practical purposes, it doesn't take a lot more time to replace all files, compared with selected files.

                                                  If you're doing this manually, most of your time is spent

                                                  1. assembling the files to be zipped. Is is faster to zip up the whole thing, or to gather just the changed files while ensuring you're not missing any?

                                                  2. Opening the zip file, clicking the extract button, selecting options and specifying the output destination. OK, you can save a second or so on the first step by dragging the file onto the unzip icon. But it costs you no more time to let the machine unzip everything. And the machine doesn''t care whether it's spending a fraction of a second or a few seconds.

                                                  Harvey
                                                  • 22. Re: Output format question
                                                    Pet3689 Level 1
                                                    Actually, this is a matter of Internet bandwidth. We provide software releases, and software patches. We try to keep our patches as small as possible. For patches, in our help documentation, we typically change less than 10%. The WebHelp ZIP would be some 10 MB large. So, this does make a difference for us. And the help documentation is only one part of the software patch of course.

                                                    But you are right of course, there is a significant risk that we may overlook an updated file. We would indeed need some fool-proof way to just extract the updated files (from multiple folders).

                                                    Well, I guess that we could ZIP up all files. Then in (Win)ZIP, we could sort the files by modification date, and remove all of the old files. Not fool-proof, but it takes care of the multiple folders dilemma.
                                                    • 23. Re: Output format question
                                                      HKabaker Level 2
                                                      I can see your point about zip files at 10 MB.

                                                      Sometimes the "newer" file should not replace the "older" one.
                                                      In other theads I've mentioned an app called Beyond Compare, which I use a great deal.

                                                      (Disclaimer: I get no reward, financial or otherwise, for recommending Beyond Compare.)

                                                      To keep this brief, it runs a comparison between two sets of files and tells you about their differences: You can set several kinds of filters, such as time/date stamp alone, size, and checksum.

                                                      You can print a report and handle the files manually. You can let the app copy/replace files to synch the two sets, or to "mirror" from one side to the other, which is not the same as synch. You can get review prompts anywhere along the way, or just let 'er rip. You can see side-by-side editable html versions of each pair. You'll know which are "orphans." File names are assumed to be identical between the two sets, but you also can order a side-by-side look at two files with different names.

                                                      Sometimes I use it to verify RH's publishing results. Sometimes I let Beyond Compare publish the changes after I've reviewed the results.

                                                      Maybe you'll find it useful, too.

                                                      Harvey