8 Replies Latest reply on Sep 17, 2009 6:50 AM by Peter Grainge

    Merging WebHelp questions

    Colette M.

      Current situation:

      Using RH v.5 (moving soon to v.8)

      Project contains approx. 1000 topics spread over 8 departments (Order Entry, Billing, Supply Chain, etc.)

      In the TOC, many topics are shared across departments since the topic impacts multiple areas.

      Home page includes What's New section with links to topics for departments.

       

      We are moving from a 1 person department to a team for 4 (thank goodness!!).  Moving from a single project to a merged project seems to be a good solution.  I've read the info on Peter's site (great stuff) and many postings on this forum.  Before I begin testing, I have several questions - some of what I've read makes me wonder if there are some things I'll need to consider for my setup.

       

      1. Does the parent project have to be empty or can I include some general topics (like a customized "how to use the online help")? I would think that having one/some topics in the parent would be wise since you need to have at least one index word.
      2. How do you link to topics from the parent project to topics in a child project?  We'll have a critical need for this on the Home page's What's New section, especially when many topics impact multiple departments. Currently, we just link within the project but I'm not sure how this is accomplished across projects.
      3. TOC - If topic resides in Billing and yet it applies to Order Entry, how do you link the topic so it appears under Order Entry?
      4. For some topics, we send emails to users with the direct link to the topic.  If we continue doing, will it open the framework of the parent project or does it bypass that and go directly to the shilc project?  If so, is there a way to get around that so users see the whole project without having to use a home button to get back to the parent project.

       

      I understand the merge process is bit different in v.8 but will need to test this out in the current version to see if it will work for our needs (vs. going to the Server version) and to get acquainted with the basic process.

       

      Thanks for any feedback to my questions and always open to suggestions/best practices.

       

      Thanks,

      Colette

        • 1. Re: Merging WebHelp questions
          RoboWizard Level 4

          Hi Colette

           

          Colette M. wrote:

           

          I understand the merge process is bit different in v.8 but will need to test this out in the current version to see if it will work for our needs (vs. going to the Server version) and to get acquainted with the basic process.

           

          I'm not sure why you think the process is different for version 8. I stand to be corrected on this, but I believe the process hasn't changed.

           

          Peter adds: It hasn't changed except for the method I advocate for redirecting from the empty parent project and that is because Firefox changed. The new method will be required in any version of RoboHelp.

           

          Colette M. wrote:

           

          1. Does the parent project have to be empty or can I include some general topics (like a customized "how to use the online help")? I would think that having one/some topics in the parent would be wise since you need to have at least one index word.

           

          Typical merging without following my fellow Adobe Community Expert Peter's advice operates exactly that way. You simply nominate one topic as being the master and it has topics inside just as the other projects will.

           

          Peter adds: Yes you can do it that way but what you want to avoid is any links between topics in this parent and topics in the child projects, or the other way around. Because the redirect I advocate starts the user in a child project without them realising it, I see no need to have topics in the parent. I just regard Child 1 as being the parent as far as content is concerned. That then allows me to have links to other projects.

           

          Colette M. wrote:

           

          1. How do you link to topics from the parent project to topics in a child project?  We'll have a critical need for this on the Home page's What's New section, especially when many topics impact multiple departments. Currently, we just link within the project but I'm not sure how this is accomplished across projects.

           

          Again I stand to be corrected on this, but I believe this reason (linking from project to project) is simplified using the approach Peter outlines with the empty parent. I understand that it's very difficult to create working links from parent to child and is much easier to create links from child to child.

           

          Peter adds:Exactly. As I have already said, links between the parent and a child are troublesome. You either have to manually edit them to start with or post generation. My way that is avoided, you have a project that has all the content you want in the parent but it is actually in a child. I don't follow why you must have it in the parent. Child 1 is part of the merge given to all users so nothing is lost.

           

          1. TOC - If topic resides in Billing and yet it applies to Order Entry, how do you link the topic so it appears under Order Entry?

           

          TOC may have topics linked wherever you like. And you may have more than one link to a topic. Of course if you do that you may see issues with properly synchronizing, but it may be done.

           

          Peter adds: How to create cross project links is covered in my tutorial.

           

          Colette M. wrote:

           

          1. For some topics, we send emails to users with the direct link to the topic.  If we continue doing, will it open the framework of the parent project or does it bypass that and go directly to the shilc project?  If so, is there a way to get around that so users see the whole project without having to use a home button to get back to the parent project.

           

          I believe you may construct links that open the whole of the frameset with the topic loaded. I know for certain it's possible to do in regular non-merged WebHelp. Pretty sure you can do it with a merged setup. I'd be surprised if Peter's site didn't have information on that somewhere. Possibly in the section where he refers to linking to help. Lemme go grab a link for you. Try clicking here.

           

          Peter adds:That's the way to do it.

           

           

          Cheers... Rick

           

           

          Helpful and Handy Links

          RoboHelp Wish Form/Bug Reporting Form

          Begin learning RoboHelp HTML 7 or 8 within the day - $24.95!

          Adobe Certified RoboHelp HTML Training

          SorcerStone Blog

          RoboHelp eBooks

           

          Message was edited by: Peter Grainge

          • 2. Re: Merging WebHelp questions
            Peter Grainge Adobe Community Professional (Moderator)

            Please see the comments I have added to Rick's reply. I have taken advantage of the fact that Rick and I are forum moderators and can edit posts. Normally that is only done if the content is offensive or suchlike. In this case I thought it would be more helpful to you to have my thoughts alongside Rick's and I hope he will not mind the way I have replied.

             

            By all means include content in the parent if that is your desire but I cannot see a single reason for not putting that same material in Child 1.

             

            As for the index, does it work in my demo, do you see any keywords in the parent when you look in the download?

             


            See www.grainge.org for RoboHelp and Authoring tips

            • 3. Re: Merging WebHelp questions
              MergeThis Level 4

              My $.02.

               

              LINKS

              The most efficient way to guarantee good cross-project linking is to let RH do it for you. That is, be sure you have up-to-date copies of every subproject on your machine as they will appear in the output. When you enter a link from ProjectA to ProjectB, for example, the destination path will initially show an absolute path (C:\<project_path>ProjectB\Topic.htm). Save and then double click the link to reopen it, and you'll see that RH has converted it to a relative path (../ProjectB/Topic.htm). A link from ProjectA to the Master would be ../../ProjectMaster/Topic.htm, and the reverse would be mergedProjects/ProjectA/Topic.htm.

               

              MASTER PROJECT

              You can, indeed, have topics in the master project, based usually on who is maintaining those topics and/or the entire merged project. As the merged project "admin," I maintain a "New User Interface" topic at the top of the TOC (above all the subproject books in alpha order), and several topics in a "Using Help" book further down. Another set of System Admin topics in their own book, however, are maintained by two other writers and myself, so is therefore a separate subproject. All other (41) subprojects are each maintained by single writers.

               

              GENERATING OUTPUT

              The beauty of a merged WebHelp system, of course, is that only updated projects need to be generated and published, as needed. This produces a nimble process at production time (a normally stressful time).

               

              SUPPORT SYSTEM

              As the merged project grows exponentially, as they eventually all do, you'll find the need for third-party tools to help you with customizing the user interface, identifying and correcting inconsistencies, instituting system-wide changes, etc.

               

              I use the following, some of which are freeware, others are shareware. I'd be lost without them.

               

              • ExamDiff Pro - Excellent compare utility
              • FAR - Find and Replace tool that ignores extra spaces and line breaks
              • Karen's Replicator - Synchronizes folders (only different topics, not the entire folder)
              • Walter Zorn's DHTML JavaScript Tooltips (completely customizable tooltips: color, position, etc.)
              • Xenu - Excellent link checker (because writers will move and rename files without cleaning up after themselves)
              • Z-Cron - Schedules off-hours batch scripts (I use it to run FAR batch processes)
              • Zoom - Excellent customizable Search engine that provides better search experience than RH (although it seems that the RH8 search is much improved)

               

               

              Good luck,

              Leon

              • 4. Re: Merging WebHelp questions
                Peter Grainge Adobe Community Professional (Moderator)

                Leon

                 

                I thought you were using the method on my site where the parent does not contain any content. Has that changed?

                 

                Can you clarify how you are creating the parent child links as mergedProjects is an output folder? The article on my site is very much like what you are advocating but with source files. I would have expected that if you are in a source topic and browse to an output folder the path would get messed up.

                 


                See www.grainge.org for RoboHelp and Authoring tips

                • 5. Re: Merging WebHelp questions
                  MergeThis Level 4

                  No, Peter, I'm not pointing the link to a child output folder, I'm pointing it to the child source folder. However, as long as I and the other writers have both the source and output folder structures on our machines, RH will take care of it.

                   

                  What I'm saying is this: if you have copies of all source and output folders on your local machine, all links will be properly transformed into relative links by RH (although you might have to manually tweak those between parent and child). In addition to a few topics in the parent, I have extra navigation toolbar buttons linking to child topics, which also works well.

                   

                   

                  Good luck,

                  Leon

                   

                  merge_links.gif

                  • 6. Re: Merging WebHelp questions
                    Colette M. Level 1

                    Thanks all for your responses to my merging questions.

                     

                    Leon - We have 4 authors who will have individual projects that will be part of a parent project.  Are you  saying that each author must have copies of all the projects on their local drives in order to link between them?

                     

                    Example: 

                    Tom has project A and B child projects.

                    Sue has project C and D child projects.

                     

                    A topic in project A contains hyperlinks to information in project D.  Does Tom have to have copies of project D on his local drive in order to make the hyperlinks work?

                     

                    We have many documents that are cross-functional and would be cross-linked like this so I'm concerned that having to constantly copying other authors' projects to an author's local drive would defeat the purpose of using merged help. 

                     

                    Thanks - Colette

                    • 7. Re: Merging WebHelp questions
                      Peter Grainge Adobe Community Professional (Moderator)

                      Leon

                      (although you might have to manually tweak those between parent and child)

                      As long as people understand that important point, then parent/child links are OK. The reason I advocate avoiding it is that there is it simplifies things, not necessary for an old dog like you.

                       

                      Colette

                       

                      I am up early while my body adjusts to jet lag so hopefully Leon and you won't mind me stepping in.

                       

                      A while back I needed more than one author working on a merge set up so this was our solution. At the start, we all had a copy of the whole lot, A B C and D in your case. Any one author only worked on their assigned project(s), they only needed the copies of the others for the purposes of creating links.

                       

                      Periodically each author would send me just their projects.  I would trash the originals and replace them with these updates (with suitable backups). Then I would issue new copies.

                       

                      It works easily and does not defeat the purpose of merged help.

                       


                      See www.grainge.org for RoboHelp and Authoring tips

                      • 8. Re: Merging WebHelp questions
                        MergeThis Level 4

                        OK, let me try again...

                         

                        Tom only has to have copies of project D on his local drive to have RH create a proper relative link for him. Tom is perfectly free to insert the proper link (../ProjectD/TargetTopic.htm) manually, in HTML mode. For a link to the parent folder, it would be ../../TargetTopic.htm (we link to a common feedback_script.js file in this manner for email comments). For a link from the parent folder, it would be ./mergedProjects/ProjectD/TargetTopic.htm.

                         

                        As I said before, from the Link to: dropdown in the Hyperlink window, select File, then the child folder and the target topic; the path will look like this (I added a space after "file" to eliminate a bad link here):

                         

                        file: //C:/main_imsmerge/projects/ProjectD/TargetTopic.htm

                         

                        Click OK. Now, double click the link you just added, and notice how RH has transformed the path into a relative link (if the ProjectD folder is in the main_imsmerge folder on Tom's machine):

                         

                        ../ProjectD/TargetTopic.htm

                         

                        I'm unclear about your thinking that "constantly copying other authors' projects to an author's local drive would defeat the purpose of using merged help." On the contrary, it's a sure-fire procedure that helps you ensure the validity of all hyperlinks in your merged help system without having to muck about in the HTML code (will all your writers be comfortable with that?). However, I'd still run a good link checker, like Xenu, to periodically check the system anyway.

                         

                         

                         

                         

                        Good luck,

                        Leon

                         

                        ===============

                        BTW, I just reread your original post, and realized we hadn't addressed this question:

                         

                        TOC - If topic resides in Billing and yet it applies to Order Entry, how do you link the topic so it appears under Order Entry?

                         

                        In the Order Entry project, you would add a redirect topic in the Order Entry project (linking it to Billing as show below) and add it to the Order Entry TOC. This redirect topic contains no content in WYSIWYG (nothing between the opening and closing BODY tags). Instead, you add a meta tag anywhere within the HEAD section of the topic:

                         

                             <meta http-equiv="refresh" content="0;URL=mergedProjects/Billing/TargetTopic.htm" />

                         

                        Clicking on the Order Entry TOC entry would immediately (note the content="0; value) open the Billing topic and synch to the Billing TOC entry. If you'd prefer to have the user see a brief explanation that they are being redirected to the help section where the topic actually resides, you could add such a blurb to the topic, and increase the 0 value to enough microseconds for the user to be able to read the blurb.