9 Replies Latest reply on Sep 6, 2007 1:17 AM by Phil_Wells

    Combine or Merge?

      Hello, my company has several software products, utilities and optional modules, all related to one another. I have a separate HTML Help project and .chm file for each one. We wish to create an All-in-One type documentation because the products are beginning to overlap quite a bit.

      My questions are: (1) Do I keep them as separate projects, and then Merge when compiling - if so, how do the TOC and Index work?; (2) Do I place everything in one project, and if so, how best to organize this? (Separate directories for screen captures, how to name files to keep everything straight, such as prepending P1 to each Product 1-related HTML file and screen capture... I believe I have read here that all the HTML files must be kept in one directory?) I have already taken one and modified it to fit this All-in-One concept, using the "P1-filename" convention, but I have a sinking feeling that maybe I'm not approaching this correctly.

      FYI, The topics will need to reference topics in the other projects.

      Please advise and get me on the right track. I would really appreciate any help.

      /Susan
        • 1. Re: Combine or Merge?
          Phil_Wells
          I would merge, but this does require a little bit of thought beforehand - particularly if you are going to produce a webhelp output as well.

          I have a similar situation to you , where the software I write Help Files for comes in several varients, each of which I can use/reuse sub-projects for. For example, I have a 'Software Overview' sub project, which gets used 5 times in different varients of the Help Files.

          The advantage of the modular approach is that it makes keeping the help files up to date a fairly easy exercise. Update the 'Software Overview' sub project and recompile it (with outputs going to the different varients of the Help Files) and everything is updated, rather than updating 5 versions of the file.

          The downsides are:

          (a) You have to set up a lot of SSL's for the sub projects - one for each master help file it is going to go into.
          (b) You have to be careful about links, etc. Change a link to a sub-project, and you might have to go to 5 master projects to correct the link.
          (c) You have to be careful about 'see also' names, etc. If you have a 'basic concepts' see also in every sub project, they will combine to form a single large 'see also' in the master project.
          (d) The sub projects cannot generally be 'nested' in the master project TOC - this is due to a RH bug that mixes up books and topics in imported TOC's - I can only get round this by having all the imported TOC's at 'ground level ' in the master TOC, not moved further upwards in the hierarchy.

          Those and one or two other caveats aside, I'd definately merge when compiling and not go for a single mega project.

          (When one of my &^@*ing developers recently took it on himself to change a GUI recently, I only had to change one sub module, not 5 help files).

          One final tip - when you generate a master project RH does not overwrite any files that might be in the output SSL. Providing you only make minor changes to the sub-projects, the way round this is to direct the output of the sub-projects to the output SSL of the master project. That way, when you recompile a sub project, it automatically puts the updated output where the master project should put it when the master project is recompiled.

          Feel free to ask further questions - I'll help as best I can.
          • 2. Re: Combine or Merge?
            Peter Grainge Adobe Community Professional
            Phil, I hope you won't mind me coming in on this as I think you are making merging sound just a bit more complex than it really is.

            At its simplest, you create a parent and the child projects. You then just install whichever of the child projects you want for a particular build.

            Take a look at the topic on my site about merging webhelp. There I describe how to have a parent with no content so that it just acts as a shell. You supply that and just whichever child projects you want. Done that way, when you generate you will find that a mergedProjects folder is created with a folder for each child and you generate each child project to just that one folder. Done that way, when you regenerate a child it updates the whole output as the whole output is in just one structure. It does not, at this level, require lots of !SSL! folders. The method can be adapted if CHM is your poison.

            Now let's move on to more complex builds. Phil had a need whereby there were different versions of each child plus other things that varied with each build. Those things could have been done by continually regenerating but it meant remembering the nuances of each build. To address that Phil came up with an elegant solution that used more than one target for a build. Imagine numerous variations. You can either apply the conditions for each build and then generate the required projects, remembering which conditions and child projects are needed for that output or, as Phil did, you create a number of parent projects which just refer to the child projects for that build. That requires different targets for each. Then each child instead of having just one webhelp output has different ones for each build expression used. Again each one has to go to the required parent's mergedProjects folder.

            I hope Phil will not mind me suggesting that first you look at my topic and get your mind around merged webhelp at a simpler level. When you understand how that is working, then is the time to consider Phil's setup if you have more complex needs as he did.

            Learn to drive something more basic before you jump into the Ferrari or you will crash first time out!

            • 3. Re: Combine or Merge?
              Phil_Wells Level 1
              Peter,

              Course I don't mind you jumping in - and indeed I may have made it seem over complex.

              As I read RoboHELP!'s problem, her situation is like mine in that she has optional modules that have to go into several help files similtaneously.

              That said, your suggestion is a good one. Merge one sub project into a master, see how that works and take it from there.





              • 4. Re: Combine or Merge?
                Level 1
                Thank you very much Phil and Peter. I now have a handle on how to proceed. Peter, I had looked at your website before posting this question, but perhaps because the topic referred to WebHelp I may have skimmed past it. Sounds like it would work the same for HTML Help. (As an aside, I have asked my technical manager about using WebHelp but she said that not everyone has IE and to stay with HTML Help. I haven't met a customer who didn't have IE, but our software CAN be run on a standalone database - say on their laptop during a flight - and then when they connect they can upload their work to the network database. Can our software try calling WebHelp first and then if that fails call HTML Help?)

                Anyway, I do plan to always compile with all modules; after all, if a customer sees information on one of our optional modules, maybe it will interest them enough to buy it!

                Thanks again for your help. This forum and Peter's site are great!

                Susan
                • 5. Re: Combine or Merge?
                  Peter Grainge Adobe Community Professional
                  The decision re the output type is based on where the help is going to reside.

                  If it is going to be on a server, you need webhelp. If it is on the user's PC, you need CHM help. You can generate webhelp now to work locally but generally it is as I have indicated.

                  What you are talking about is described as airplane help precisely because it works locally when offline. That could be webhelp configured to run locally. Then you get into issues about updating the web version and the local version.

                  If you think of using webhelp and CHM, there's another gotcha. The links between the topics in the merge are created in a totally different way so you have to create two versions of every link and then apply conditions.

                  In the topic on merged webhelp, I describe how to set up the parent as a redirect. For CHM help, you would need to create a separate parent and just have a vanilla "Welcome to Paradise" topic with no links.

                  Does it feel like time for a coffee now?

                  When you get back, play around with some merging keeping it small so you can see what is going on. Good luck. It's not as difficult as it may seem.

                  • 6. Re: Combine or Merge?
                    PeterHATT
                    We are contemplating similar scenarios. Then again, perhaps our case is a bit different?

                    We have two software products, which are different but also overlap. Some time ago, our Help writer took a snapshot of the Help from Product1 and modified it to create Help for Product2. I suppose that the reason was that this Help writer was not familiar/comfortable with Conditional Build Tags and User-defined Variables. However, some 50% of the Help pages of Product1 and Product2 are very similar, and even the screenshot are often almost the same.

                    We would like to combine the Help for Product1 and Product2, so that they can share images (screenshots) and Help pages (using Conditional Build Tags and User-defined Variables).

                    For example, if a GUI changes, we now often need to make the same changes twice. We would like to make such changes only once.

                    We understand the idea behind merging, to some extent anyway. But it seems that this would not resolve our issue of file-sharing between "projects", correct?

                    With RoboHelp for Word, we managed to combine Help projects quite easily, by simply adding the documents with the "new" Help to the "old" Help project.

                    However, we switched to RoboHelp HTML some time ago, and now combining is not to obvious anymore. We thought that "exporting" to XML Output and then Importing XML would work. However, "exporting" to XML of a very modest project (50 pages Printed Documentation) progressed to perhaps 20% in 24 hours.

                    We also tried to copy the files from project 1 into the folder for project 2, but that overwrites the settings (TOC, Index, etc.) of project 2. Do the "images" and "html" folders need to be in the root of the Help project?

                    Any thoughts?

                    Thanks (and I apologize for the length of this "Reply")!
                    • 7. Re: Combine or Merge?
                      MergeThis Level 4
                      PeterHATT:

                      You might consider a "working" project, which would contain all topics and graphics, and from which you could "feed" any number of other projects by importing topics from the "working" project.

                      For example:
                      1. All work is done in the single MySandbox project.
                      2. The MySandbox project is copied and renamed to Project1, Project2, etc.
                      3. Project1, Project2, etc., are tailored as needed (TOC, Index, etc.).
                      4. As changes are made to the MySandbox project,:
                      4a. Compare the directories for topic differences.
                      4b. Open Project1, Project2, etc..
                      4c. Import (not copy) new and modified topics from MySandbox (older topics get overwritten).

                      A bit unorthodox, I know. However, if the concepts of merging and conditionalizing won't fit well in your environment, it might be worth a shot!


                      Good luck,
                      Leon
                      • 8. Re: Combine or Merge?
                        ---Dirk_Bock Level 1
                        quote:

                        Originally posted by: PeterHATT
                        We are contemplating similar scenarios. Then again, perhaps our case is a bit different?

                        We understand the idea behind merging, to some extent anyway. But it seems that this would not resolve our issue of file-sharing between "projects", correct?


                        It could resolve your file-sharing issues with several limitations. For this task you would create three projects for RH:

                        1) Project 1: specific topics for Product 1
                        2) Project 2: specific topics for Product 2
                        3) Project X: topics relevant for Product 1 and Product 2.

                        To generate help for Product 1, you'll prepare Project 1 and merge Project X; the same goes for Product 2. If you change something in Project X, you only generate a new version of the Project X output.

                        If you are working with HTML Help (at least) the limitation is that the Table of Contents of Project X can only appear as a single 'block' in the Table of Contents of Project 2.

                        This scenario works best if the contents of Project X is more or less stable. If it changes regularly, on the other hand, you have to make sure that the most up-to-date version of the Project X help is delivered for all Products. This is not hard to do, but a source for errors nevertheless.

                        Regards

                        ---Dirk Bock

                        • 9. Re: Combine or Merge?
                          Phil_Wells Level 1
                          I have a situation where my company has a very modular product with certain sections of the help beimg repeated between main modules. For example there is a Configuration sub-module that can be called from five of the main modules.

                          What I do is write the help files in a very split up form, then merge them as required. This means once the Configuration sub-module has been written it can be merged into the five main help files that use it. My master help files might contain 10 - 15 merged sub projects.

                          It is possible to do this in a way that you can product both .chm and webhelp from the same set of projects/sub projects. I did this by adapting Peter Grainges webhelp merging method slightly - go to the following link and scroll down to the 'Multiple Parents and Multiple Outputs' section for an explanation.

                          http://www.grainge.org/pages/authoring/merging_webhelp/merging_method.htm

                          You have to think a bit beforehand about the sub-projects needed and the directory structures they are going to go into. You also have to be aware of some of the known RoboHelp bugs, but once the structure is set up it makes maintaining help files very simple. For example, if I need to update the Configuration sub-module I update the original sub-project then batch generate it to all the associated master projects - result: 5 help files updated at a time.