• Global community
    • Language:
      • Deutsch
      • English
      • Español
      • Français
      • Português
  • 日本語コミュニティ
    Dedicated community for Japanese speakers
  • 한국 커뮤니티
    Dedicated community for Korean speakers
Exit
0

Project structure input needed

Explorer ,
Jun 10, 2009 Jun 10, 2009

Copy link to clipboard

Copied

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

Views

1.4K

Translate

Translate

Report

Report
Community guidelines
Be kind and respectful, give credit to the original source of content, and search for duplicates before posting. Learn more
community guidelines
Advisor ,
Jun 10, 2009 Jun 10, 2009

Copy link to clipboard

Copied

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

Votes

Translate

Translate

Report

Report
Community guidelines
Be kind and respectful, give credit to the original source of content, and search for duplicates before posting. Learn more
community guidelines
Explorer ,
Jun 10, 2009 Jun 10, 2009

Copy link to clipboard

Copied

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

Patrick

Votes

Translate

Translate

Report

Report
Community guidelines
Be kind and respectful, give credit to the original source of content, and search for duplicates before posting. Learn more
community guidelines
Valorous Hero ,
Jun 10, 2009 Jun 10, 2009

Copy link to clipboard

Copied

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

Votes

Translate

Translate

Report

Report
Community guidelines
Be kind and respectful, give credit to the original source of content, and search for duplicates before posting. Learn more
community guidelines
Explorer ,
Jun 10, 2009 Jun 10, 2009

Copy link to clipboard

Copied

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

Votes

Translate

Translate

Report

Report
Community guidelines
Be kind and respectful, give credit to the original source of content, and search for duplicates before posting. Learn more
community guidelines
Advisor ,
Jun 11, 2009 Jun 11, 2009

Copy link to clipboard

Copied

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

Votes

Translate

Translate

Report

Report
Community guidelines
Be kind and respectful, give credit to the original source of content, and search for duplicates before posting. Learn more
community guidelines
Explorer ,
Jun 11, 2009 Jun 11, 2009

Copy link to clipboard

Copied

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

Votes

Translate

Translate

Report

Report
Community guidelines
Be kind and respectful, give credit to the original source of content, and search for duplicates before posting. Learn more
community guidelines
LEGEND ,
Jun 11, 2009 Jun 11, 2009

Copy link to clipboard

Copied

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

Votes

Translate

Translate

Report

Report
Community guidelines
Be kind and respectful, give credit to the original source of content, and search for duplicates before posting. Learn more
community guidelines
Participant ,
Jun 11, 2009 Jun 11, 2009

Copy link to clipboard

Copied

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

Votes

Translate

Translate

Report

Report
Community guidelines
Be kind and respectful, give credit to the original source of content, and search for duplicates before posting. Learn more
community guidelines
Explorer ,
Jun 11, 2009 Jun 11, 2009

Copy link to clipboard

Copied

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

Votes

Translate

Translate

Report

Report
Community guidelines
Be kind and respectful, give credit to the original source of content, and search for duplicates before posting. Learn more
community guidelines
Guest
Jun 11, 2009 Jun 11, 2009

Copy link to clipboard

Copied

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

Votes

Translate

Translate

Report

Report
Community guidelines
Be kind and respectful, give credit to the original source of content, and search for duplicates before posting. Learn more
community guidelines
Explorer ,
Jun 11, 2009 Jun 11, 2009

Copy link to clipboard

Copied

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

Votes

Translate

Translate

Report

Report
Community guidelines
Be kind and respectful, give credit to the original source of content, and search for duplicates before posting. Learn more
community guidelines
Engaged ,
Jun 11, 2009 Jun 11, 2009

Copy link to clipboard

Copied

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

Votes

Translate

Translate

Report

Report
Community guidelines
Be kind and respectful, give credit to the original source of content, and search for duplicates before posting. Learn more
community guidelines
LEGEND ,
Jun 11, 2009 Jun 11, 2009

Copy link to clipboard

Copied

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

Votes

Translate

Translate

Report

Report
Community guidelines
Be kind and respectful, give credit to the original source of content, and search for duplicates before posting. Learn more
community guidelines
Engaged ,
Jun 11, 2009 Jun 11, 2009

Copy link to clipboard

Copied

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

Votes

Translate

Translate

Report

Report
Community guidelines
Be kind and respectful, give credit to the original source of content, and search for duplicates before posting. Learn more
community guidelines
LEGEND ,
Jun 11, 2009 Jun 11, 2009

Copy link to clipboard

Copied

LATEST

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

Votes

Translate

Translate

Report

Report
Community guidelines
Be kind and respectful, give credit to the original source of content, and search for duplicates before posting. Learn more
community guidelines
Engaged ,
Jun 11, 2009 Jun 11, 2009

Copy link to clipboard

Copied

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

Votes

Translate

Translate

Report

Report
Community guidelines
Be kind and respectful, give credit to the original source of content, and search for duplicates before posting. Learn more
community guidelines
Resources
RoboHelp Documentation
Download Adobe RoboHelp