16 Replies Latest reply on Jun 11, 2009 3:30 PM by Captiv8r

    Project structure input needed

    James K. Patrick

      Hello all,

       

      I'm new to RH8 and just starting a new WebHelp project that will span several phases over the next year or two. Over the last few weeks I've been gaining experience with the product, kicking the tires, going through self-paced training, etc.

       

      I'm interested in learning a few tidbits of wisdom from folks who have a some RH projects under their belts already. I believe I understand the basic philosophy RH uses in its approach to information management. And I fully realize I'll make plenty of mistakes on this first project (and the second one).

       

      So what I'm interested in learning are the little things that can be done when planning out the project structure in RH to avoid a royal mess later on.  Things like:

       

      Boy, I wish I'd spent more time planning out my Master Pages because...

       

      or

       

      If only I'd known about using the XYZ feature - then I wouldn't have to rework all this content...

       

      Really I guess I'm trying to avoid having too many DUH! moments at the end of my first project phase when I evaluate it. So, folks, what was it on your early projects that caused you a DUH! moment? What would you have done differently in setting up your project to make your life easier down the road?

       

      Thanks for helping me reduce my DUH! level,

       

      Patrick

        • 1. Re: Project structure input needed
          MergeThis Level 4

          I would stay away from:

          See Also links

          Related Topics links

          Popup and dropdown text

          Browse sequences

          Glossary

           

          Quite frankly, I've found these to be more trouble than they're worth, especially as Web browsers proliferate (as do their related plugins). In addition, troubleshooting these beasties might require more HTML knowledge than you possess when starting out. My mantra (related to using cutesy features) has always been: just because you can, doesn't mean you should. In other words, create your online help as you would drive: defensively.

           

          If you must have a Glossary, create a topic with that name, create a GHead and Gtext style, set up bookmarks to each "alpha" heading, and add links at the top to each of those alpha headings.

           

          Two output issues to avoid:

          Output in !SSL! folders (using version numbers and product acronyms, we use C:\902_xxxmerge and C:\902_xxxgenerate for source and output)

          Output under My Documents (often set up by your IT peeps to be a virtual network folder; bad news for RH)

           

           

          Good luck,

          Leon

          1 person found this helpful
          • 2. Re: Project structure input needed
            James K. Patrick Level 1

            Thanks, Leon. These are just the kinds of tidbits I'm looking for.

             

            Patrick

            • 3. Re: Project structure input needed
              RoboWizard Level 4

              Hi all

               

              And now for the flip side...

               

              I regularly use Related Topics and See Also controls. They have never caused me issues or hardships. I don't really consider them to be "cutesy". Quite the opposite. They can be very powerful features when they are needed. And perhaps that's the difference. Just because a feature exists doesn't mean it should be used in all circumstances. Therein lies the rub. Knowing what feature to use and what circumstances create the need.

               

              I will also use the other features Leon doesn't seem to like. Again, it's more of a matter of knowing when each feature will come in handy.

               

              I'm sorry, but I'll have to agree with Leon on one bit he mentioned and totally disagree on another.

               

              Leon advised that you should deviate from the !SSL! output folder. I disagree with that and will tell you that I've seen issues arise when folks do that. You don't want to do this lightly. There needs to be good reasons for doing so. In my humble opinion, Merged WebHelp is not a good reason.

               

              I DO agree with being cautious with the whole My Documents thing. I regularly advise folks in all my RoboHelp and Captivate classes to consider creating a folder right off the root of your C drive. Call it Projects if you like.

               

              C:\Projects

               

              As you accumulate projects, create a new folder for each one.

               

              C:\Projects\Project One

              C:\Projects\Project Two

              etc.

               

              On my own hard drive I use a folder named C:\Rick for this purpose. It keeps the path short and that can save you some headaches down the line.

               

              Before embarking on a project, consider the features RoboHelp offers that will assist. For example, Snippets are great for standard text that you find yourself repeating over and over and over and over... Variables and Variable Sets are good. I consider with any new project I would say to create at least three new variables.

               

              • CompanyName
              • CompanyAcronym
              • CompanyURL

               

              If you are using RoboHelp 8, you may use the advantage of formatting the variables. So the CompanyURL will also contain the link that is used. Then you may populate the topics with the right items as you work. If the items ever change on you, it's super simple to fix. You just specify a new value for the variables!

               

              I'll stop here. But there are lots of different things to consider. When I facilitate my classes I usually toss in all the different issues and potential pitfalls you may see. There are enough that I've considered an eBook just for the little tidbits.

               

              Cheers... Rick

               

               

              1 person found this helpful
              • 4. Re: Project structure input needed
                James K. Patrick Level 1

                Rick,

                 

                Thanks for the input. Different ways of looking at things are always welcome.

                 

                I've already setup with a folder directly off C:.

                 

                Any other folks out there willing to share some wisdom?

                 

                Patrick

                • 5. Re: Project structure input needed
                  MergeThis Level 4

                  Rick, the environment tends to dictate what bells and whistles you will include. Yours seems to be single-writer, single-project HTML Help projects. In ours, all style and formatting issues are dictated by the fact that there are seven writers dealing with 42 projects, delivering merged WebHelp. Some of the writers still have trouble identifying the relationship between source and output files, and would simply be incapable of troubleshooting these beasties.

                   

                  Until RH8, with its improved RoboSource Control, we were managing our X502 projects without any source control (periodically copying source folders to a server for backup). What good reason might there have been for us to include all !SSL! output folders? I can't think of one!

                   

                  And yes, Rick, merged WebHelp has its own idiosyncracies, and must still be handled with kid gloves.

                   

                  And oh, by the way, Patrick, I'd also stay away from the RH8 table styles and multilevel list styles; neither feature was ready for prime time when they shipped the product. Another forum member mentioned that, as a result of his repeated complaints, Adobe provided him with a .dll file to correct the multilevel list style problem, but it doesn't appear that they would be willing to share it with the rest of us. WHAT???????????

                   

                   

                  Good luck,

                  Leon

                  • 6. Re: Project structure input needed
                    NL_Derek-GsBV5a Level 1

                    I would also watch out for special characters -- anything other than a-z 1-9 underscore space may come back to bite you. Personally I even avoid spaces in filenames. Of course you can use everything in your content, but keep filenames and also topic names simple.

                     

                    Enjoy RH!

                     

                    --- Derek

                    • 7. Re: Project structure input needed
                      James K. Patrick Level 1

                      Leon,

                       

                      Thanks - good to hear about features that may be quirky. I've got reference data to write in this project and was going to use table styles. Will have to do some more digging on that point now.

                       

                      Patrick

                      • 8. Re: Project structure input needed
                        James K. Patrick Level 1

                        Derek,

                         

                        Yeah, it's already been drilled into me to avoid spaces in filenames. I'm definitely working to keep this first project simple.

                         

                        Patrick

                        • 9. Re: Project structure input needed
                          ElisaFnord Level 2

                          A small but helpful tip - if you use topic templates to put repeated information on all topics, remember to keep your boilerplate text (copyright statement, etc.) in the template header and footer. Updated boilerplate text in the template body shows up when you create new topics from the updated template, but changes to the template body text are not propagated to existing topics.

                           

                          Sounds obvious, right? But I changed my mind about wording at the last minute on one project and had to make changes by hand!

                           

                          I haven't tried this yet, but I think that if you put a snippet in your template body, you can then change existing topics by changing the snippet content.

                           

                          Elisa

                          • 10. Re: Project structure input needed
                            James K. Patrick Level 1

                            Elisa,

                             

                            Great timing! I'm just now figuring out headers/footers, templates and the like. I think I'll try both ways you suggest, since I'm working in a test project at this point.

                             

                            Patrick

                            • 11. Re: Project structure input needed
                              Gravenstein Level 2

                              Great topic!

                               

                              I'm with Leon on the !SSL! thing. I deal with lots of writers, and sometimes there will be a writer who is new to the RH authoring process. There is simply less opportunity for error if the generated output goes somewhere totally outside the project. One poor writer managed to totally overwrite her source files with her output files when she didn't specify her output location quite right. Ouch. This doesn't happen when there is a clearly specified, and separate, location for the output files.

                               

                              Other than safety, there's a second reason why I like to separate the source and output files. We make regular backups of our source directories and store them in a common location. (Actually, that's another thing I'd highly recommend doing. You would not believe how useful this has been.) Having the output files embedded inside the source directories would really bulk up the amount of space needed for storage.

                               

                              We also use merged projects, and I find it simpler to manage this with the output location being outside the project source.

                               

                              G

                              • 12. Re: Project structure input needed
                                Gravenstein Level 2

                                Some other suggestions:

                                 

                                1. File naming conventions. Figure out what you need and document your standards. Good file naming can be hugely useful.

                                2. If you have a family of related help projects, make them as parallel as possible in structure.

                                3. Organize your project into subfolders, but don't go too deep. Windows imposes a limit of 256 characters on the full pathname of a topic.

                                4. If you are including an index, figure out how you want to do subentries and stick with that plan. It's really easy to do it more than one way and end up with kind of a mishmash.

                                5. Make heavy use of templates and stylesheets. Severely punishauthors who go off and manually format their help text. Significant manual formatting practically guarantees extra maintenance work down the line.

                                6. Back up your work. Frequently. Even if you are using source control.

                                7. Something I'd do differently if I had to do it over again is the naming of my output start file. I'd name it "index." What I *did* do was get the concept of the launch file and the default topic confused, and so I repeated the name of the default file. Now that bad decision has lived on, and I've been stuck with the resultant confusion for years! (I am slapping my wrist right now.)

                                8. If you are working with a team of writers, consider creating reference models/examples of each topic type. This can help with consistency.

                                9. Document design and standards decisions as you make them.

                                10. Put one person in charge of templates, stylesheets, and skins. They can rapidly spin out of control if everybody makes changes.

                                 

                                G

                                • 13. Re: Project structure input needed
                                  Captiv8r Adobe Community Professional & MVP

                                  Hi G

                                   

                                  I can't fathom that occurring. RoboHelp simply will not allow you to specify the source location as the output destination. I've tried. Repeatedly

                                   

                                  (I tried when I was attempting to sort how folks were managing to overwrite their source. I figured that was the likely cause.)

                                   

                                  You said:

                                  This doesn't happen when there is a clearly specified, and separate, location for the output files.

                                   

                                  Okay, I do agree with that. But, ummm, last I checked, !SSL!\WebHelp *IS* a clearly specified (and separate) location for the output to end up, is it not? I mean, the very fact you are attempting to instruct folks to deviate from the default location would seem to be hazardous if they don't know enough about the Windows File system to know what they are doing.

                                   

                                  Cheers... Rick

                                   

                                   

                                  • 14. Re: Project structure input needed
                                    Captiv8r Adobe Community Professional & MVP

                                    Hi Leon

                                     

                                    I would heartily agree with you regarding the environment dictating the approach. You are partly correct from the standpoint of my situation being a single writer. I've worked in both environments. As a lone writer and as a group. And now I simply use RoboHelp as a lone writer for what I do with facilitating my classes. (Yep, still use RoboHelp each and every day! I keep all my training materials in a CHM format)

                                     

                                    What I was concerned with was your statements coming off as a blanket "you should never do this" implication. Each situation is different. I might even suggest that there are far more lone writer setups than huge shops as yours. So I'd say your setup is probably the anomaly. The exception where you need to approach things differently.

                                     

                                    I have to somewhat disagree about the bit regarding handling Merged WebHelp with kid gloves. Certainly one must be careful about where you place things in order to make them work, but it's pretty stable otherwise.

                                     

                                    You are spot on with not needing to make backups of your output files. But personally I find it easy enough to exclude them from the mix if I need to.

                                     

                                    The thing is, as RoboHelp installs and creates output, it simply works and works pretty well. It's much easier to say just use the default setup (which should work for the majority of users) than to create elaborate schemes where you are constantly deviating from the defaults.

                                     

                                    I can't help but to feel my differing viewpoints have ruffled your feathers a bit. Sorry if they did. That certainly wasn't the intent. I simply wanted to point out that yours is a special case and as such should not be considered a blanket best practice for all users of RoboHelp. Expecially if that is remotely capable of helping some inadvertently shoot themselves in the foot.

                                     

                                    Please note that what I'm about to say next is not intended to infer any inside knowledge. It is simply speculation, pure and simple. (Sometimes folks think that as Adobe Community Experts we have all this wonderful inside knowledge about upcoming things. Once in a blue moon we may, but by and large we find out when you do.) As for the person not making the DLL available to the general population, it wouldn't surprise me in the least to see that a patch is soon issued for RoboHelp. It's common to see such things after release. Captivate 4 has already seen a patch.

                                     

                                    Cheers... Rick

                                     

                                     

                                    • 15. Re: Project structure input needed
                                      Gravenstein Level 2

                                      Rick,

                                       

                                      Thanks for that input on not being able to overwrite the source. Good to know that my worry has been groundless. However, I am now *totally* mystified as to how the writer accomplished the task, because she did indeed overwrite her source files somehow!

                                       

                                      You are probably correct in recommending the simple, default approach for most users. I am satisfied that our setup is appropriate to our case, but the size and complexity of our help project family is not really the norm. And I'll be the first to admit that it takes a lot of admin effort to keep the whole thing going.

                                       

                                      Cheers,

                                      G

                                      • 16. Re: Project structure input needed
                                        Captiv8r Adobe Community Professional & MVP

                                        Hi G

                                         

                                        In my own experience with assisting others, overwriting the source files may occur in two basic ways.

                                         

                                        1. The author is too cocky or simply doesn't know what they are doing and they open Windows Explorer and copy files the manual way. Back when I was in the corporate world we saw a complete folder and gobs of subfolders of an application suddenly disappear and everything crashed when a user did this on the corporate network. Hey, things happen. This person refused to acknowledge he did anything wrong.
                                        2. The author attempts to configure a publishing destination and mistakenly selects the project source location as the publishing destination. I'm thinking this one should be a fairly easy fix for the RoboHelp development team to fix as they have with the WebHelp output location. I'm thinking it would be as simple as checking for the existence of an .XPJ file and refusing to publish to a folder containing one.

                                         

                                        Cheers... Rick