12 Replies Latest reply on Jun 8, 2011 7:59 AM by LaKisha1

    1 RH Project, 2 Users - Best Practices

    LaKisha1 Level 1



      I've been the sole writer at our company for 6+ years. I finally have someone to help me; however, this has introduced a new challenge. We will *both* be working on the same RH project, and we will be using VSS for source control. I'm not sure how we should be 'sharing' this single RH project.


      Does anyone have any best practices for when working in this type of situation?


      I have questions such as:

      • When the other person is creating Index keywords, what if I have files checked out - how will this affect the adding of keywords?
      • When the other person creates new snippets or new user-defined variables, should he immediately check them in and let me know so that I can do a get latest and have the new snippets/variables in my project?
      • How do we manage both of us working on the same project, and having the need to check in/check out files, create new topics, etc. - what should our 'workflow' be?


      Thanks in advance for ANY assistance/tips that any of you can provide!

        • 1. Re: 1 RH Project, 2 Users - Best Practices
          Author care Level 2


          I recently faced a similar situation (we use TFS here incidently). What I did was to split the main help project into a merged help system with a master project and sub projects and then enforced a strict rule that only one author may checkout one project at a time. Our TFS revision control software was configured to forbid multiple checkouts of the same material.


          Whilst you can both work on different topics in the same help project simultaneously in my opinion this is a messy way to author.

          The golden rule here is to keep things simple and robust and don't be swayed by non authors in your course of action.

          • 2. Re: 1 RH Project, 2 Users - Best Practices
            Peter Grainge Adobe Community Professional



            Thanks for suggesting an alternative.


            Doesn't that restriction only become necessary in a source control system that does not prevent more than one person checking out a topic?


            Other than for version control purposes, you could achieve what you are doing without source control. Each author would just give you back "their" project and you would then generate. We have done that on occasion and it works just fine.


            As you will have found, splitting out the project is not a five minute task if you have links that will be between topics ending up in separate projects.




            I'll move this thread to the Source Control forum in the hope that the specific questions also get answered.


            See www.grainge.org for RoboHelp and Authoring tips



            1 person found this helpful
            • 3. Re: 1 RH Project, 2 Users - Best Practices
              Gravenstein Level 2

              I like Author Care's golden rule: keep things simple and robust. This topic touches on the three basic ways of sharing help authoring tasks. In order of complexity:


              1.  Serial authoring. If you don't need to have both authors in the project at the same time, you can simply take turns working on the project. Just pass the files back and forth as needed. This is the most simple and robust approach.


              2. Merging projects. If you need concurrent authoring, then, yes, this is a simpler and more robust approach than source control. However, this only works if you can partition your material and your work assignments into two or more clearly-delineated parts. Merging projects can be a great solution, but it doesn't fit all cases.


              3. Source control. If multiple authors need concurrent access to the same material, then source control is the simplest answer.


              Here are some tips and observations, based on my experience with RoboSource Control, in no particular order:


              1. Source control works best on small-to-medium-sized projects. Large ones can be unstable.

              2. Set it up to restrict file checkouts to one author only. Allowing two authors to work on a single topic simultaneously is bad.

              3. If possible, try to work in different areas of the project that don't touch. Remember that a single change in one topic can ripple out to many related topics. (For example, if you change the filename of a topic, every link to that topic must be changed.) If someone else is working in one of those related topics, you will not be able to complete your initial change.

              4. Make backup copies of your projects regularly, even though they are in source control.

              5. Create an administrator account to be used just for that purpose. Don't use that account for regular authoring. Don't give everyone administrative privileges.

              6. Designate one person as the administrator. Have at least one backup administrator. These will be the people who set up user accounts, override checkouts ("I need that file, and Joe is on vacation!"), resurrect old files, sort out source control conflicts, etc.

              7. Check in files as soon as you're done with them. Don't leave them checked out longer than necessary.

              8. If you have large projects, your virus scan utility can really degrade performance during certain operations, such as the initial "get" of project files. If this is the case, you might be able to configure your antivirus program to be friendlier to these source control activities.

              9. The help authors should stay in close communication. Let each other know what you're doing, especially if you are doing something radical like moving folders around. Be ready to check something back in if someone else needs it.

              10. Give a lot of thought to how your project is structured. Consider file structure, naming conventions, etc.

              11. Some actions are more source control intensive than others. (Moving, deleting or renaming folders are biggies.) Your project is vulnerable while these changes are in progress. If something goes wrong before the process is complete, you can end up with a mess on your hands. For example, let's say there's a network glitch while you're moving a folder, interrupting your connection with source control. You can end up with RH thinking that the folder is in one place, while source control thinks it's in another. The result is broken links and missing files. Time for the administrator to step in and sort things out. This is almost never a problem for small projects. It becomes a real issue for large projects.

              12. If you're getting close to a deadline, DO NOT pick that time to reorganize and rename files and folders.

              13. Follow the correct procedure for adding a project to source control. Doing it wrong will really mess you up. Adding a project to RoboSource Control is easy. I can't speak for other source control solutions.

              14.  You might find it necessary to rebuild your cpd file more often than with non-source controlled projects.

              15.Have I mentioned lately that you should back up your source files?




              • 4. Re: 1 RH Project, 2 Users - Best Practices
                Gravenstein Level 2

                LaKisha!, to answer your specific questions:


                If one author is creating index keywords, when another has files checked out...I think it depends on how you have your indexing set up, whether the entries go into the topics or into a single file. (Feel free to jump in on this anyone.) If what he is doing requires a change to a topic that he can't check out, then I don't think he can complete the action. You could test this and see whether it's a problem or not. If someone is doing a large-scale action, it might be better for the other authors to stay out of the project while it's going on.


                When someone creates new snippts or variables, is it best to check them in immediately...I would think that sooner would be better than later, but that'll be up to you and your team to decide. Be sure to keep each other informed about what your doing in your shared project.


                How do we manage both of us working on the same project...what should our workflow be? When you open the project, get the latest version of the files. If you are working in unrelated areas of the project (recommended), you process will be more or less the same as in a non-source controlled project. Check in topics, especially any common files, as soon as you're done with them. If you need to make any large-scale changes to the project, discuss them in advance with the other writers, and arrange to do so while they are not in the project.


                Truly, you and your team need to decide what your workflow is. Will you specialize, or will you decide that everyone does everything? For example, for consistency, you could decide that one person is in charge of laying out the structure of the project and creating each new topic, while the other person focused on technical content. Will you work only in folders A-F, while your neighbour works in G-M? Who will be the source control administrator?


                Sorry, more questions than answers, perhaps.



                1 person found this helpful
                • 5. Re: 1 RH Project, 2 Users - Best Practices
                  LaKisha1 Level 1

                  Hi Peter,


                  Thanks for indicating the move to source control area. i did consider starting this thread there, but thought that the higher-level general area was more appropriate. in hindsight (and 2nd-guessing myself) I agree with you.

                  • 6. Re: 1 RH Project, 2 Users - Best Practices
                    LaKisha1 Level 1

                    To Gravenstein:

                    How do I do #14 (rebuild CPD file). Mine is HUGE and I'd love to take a stab at rebuilding it to see if it gets smaller.


                    To All:

                    I've already been using VSS as the source control tool for my project for 6+ years, but since I've been the only one, I simply kept the entire project checked out, and just checked it in on occasion. But now I have to get used to *not* doing that.   THANKS SOOO MUCH for the useful feedback and tips.

                    • 7. Re: 1 RH Project, 2 Users - Best Practices
                      Gravenstein Level 2

                      You're welcome!


                      You have a backup of the project, right? :-)  With the project closed, just delete the cpd file, and then open the project in RH. RH will build a new cpd file for you. Beware, in large projects this can take quite a while.



                      • 8. Re: 1 RH Project, 2 Users - Best Practices
                        LaKisha1 Level 1

                        OOOPPS, Peter, I just realized that I actually ended up posting this question in 'other single source layouts' (not the general RH area as i thought i did)! wow, i certainly didn't mean to do that!

                        • 9. Re: 1 RH Project, 2 Users - Best Practices
                          LaKisha1 Level 1

                          oh wow, take a while - ok, got it.  I'll try it out when I'm in the office tomorrow. yep, i keep backups.

                          • 10. Re: 1 RH Project, 2 Users - Best Practices
                            Amebr Level 4

                            If both of you will be working on the same project every day, I highly recommend getting into the habit of deleting the cpd first thing each day.  (I find doing it first thing every day means I don't forget on the one occasion when it's actually necessary. )   I tend to do a Get as well to ensure I have all the latest files. This will show up any issues if people have been moving files around (broken links, missing topics, etc). RH 8 I think brought in a checkbox that deletes the CPD automatically on close.


                            However, if your project is one that takes 20min or more to re-build then this won't be practical. In this case, communication is key. Tell each other when you are about to rearrange, create, delete topics, etc so you can delete the cpd and get the latest files after these changes to ensure everything is synced. If you can, plan for one person to make all of these changes at one time to minimise how often you have to delete this file.


                            And backups outside of VSS are also useful to deal with RH deleting added files and adding deleted files in source control because it was out of sunc with VSS - while possible to get everything back from VSS, sometimes it's just easy to copy from a zip backup.



                            • 11. Re: 1 RH Project, 2 Users - Best Practices
                              Peter Grainge Adobe Community Professional

                              Take it easier today, you didn't post it in this forum, I moved it for you.


                              See www.grainge.org for RoboHelp and Authoring tips



                              • 12. Re: 1 RH Project, 2 Users - Best Practices
                                LaKisha1 Level 1

                                Thanks Amebr and Peter