Reusing topics in different projects - storing once in VSS

[Guest]

Hi, I’m new to the forum, do not currently use RH but our company is planning to purchase Adobe TCS soon.

Here’s my question: with RoboHelp and VSS, is there a way to store a single copy of an html file in VSS, but reuse the file in multiple help projects?  For example, we have a “Customer” field topic that is linked to from multiple screen topics in 5 different help projects.  I’d like to store the field topic once in VSS, rather than have 5 separate copies to maintain.  We would be reusing probably 2,000 files (out of a total 13,000 HTML files) in multiple projects.

Or maybe there is some better way to handle this that you can suggest…?

[RoboColum_n_]

There are some potential ways of getting around this duplication issue but without knowing a little more about your requirements it is hard to suggest which would be best. Would all 2000 topics be used in all projects or just some? Also I assume that these 5 help systems are completely separate.

---

The RoboColum(n)

@robocolumn

Colum McAndrew

[Guest]

Some of the 2000 topics are used in all of the other help projects, but others of the 2000 topics are used in 2 or 3 of the other help projects.  I haven't done an analysis of which ones would be used where because there are so many cross-references overall.

I'm not sure what you mean about the help systems being completely separate.  The help systems represent application modules that might be used together, and if so, they will be merged at run time. At least, that's my current plan.

[Willam_van_Weelden]

Hi,

VSS has a linking utility to share a file over multiple branches. Very handy for style sheets etc, but when I migrated to TFS, I lost that function. Also, linking is not something you can do in RoboHelp itself, you have to do this manually in VSS. Therefore you may want to check out other options, for example:

  - Using the RoboHelp Resource manager

  - Using Merged Projects

Greet,

Willam

[MergeThis]

I don't think that the Resource Manager would help here, Willam, since RH does not allow topics to be managed (images, snippets, master pages, yes).

However, a combination of merged project layouts and conditional build tags might do it. The trick will be to identify which (how many) conditionals will apply to each topic, and which topics will actually appear in each layout. Two things to keep in mind:

• Good practice is to exclude conditionals in the build tag statement (NOT admin, NOT user, etc.), not include them.
• Any topic without a conditional is always included in any layout.

Start by accessing Peter Grainge's excellent merged help tutorial. Then experiment with a small project and get a feel for how the layouts and conditionals will work. RH also has a batch generate function that will allow you to build all the layouts at once.

If more than one writer will be working on this, you might look into a good source control product. We've had no luck with RH's product, so we're switching to TortoiseSVN, a free product. VSS is also quite good.

Good luck,

Leon

[RoboColum_n_]

The key issue here is if not all of the topics will be used in all the projetcs, how the topics are organised. My initial thinking was a merged project but this may not work if not all the topics are required. It could though if you use conditional build tags to create different versions of the output from the same source and include these in the 5 projects. Otherwise the only other option would seem to be having duplicate topics inside each help file which is what we are trying to get away from.

---

The RoboColum(n)

@robocolumn

Colum McAndrew

[Guest]

My goal was to not have all 13,000 help topics under one RH project, for these reasons:

1) We will have up to 5 writers working on the help at one time.

2) There is a "core" application that is always installed, and then there are multiple optional pieces that may or may not be installed.  I was planning to set up the help for the optional pieces as separate projects that are merged at runtime.

I have worked through Peter Grainger's merged help file information with a test version of RH, and it worked.  But the problem arises because of all of the cross-references in the different modules to the reusable field topics (described in the first part of this thread).

Our help topics are already in VSS. Currently we have all our HTML help files stored (in subfolders) under one root folder.  If we use different RH projects, it appears that the files for each project have to be stored under the RH project (module) folder in VSS. I am trying to avoid maintaining multiple copies of the same topics.

We do plan to use conditional text for other purposes. For example, some product and screen names are different in different versions of the application.

I'm sorry this is such a complex scenario - but that is why we need RoboHelp!

[MergeThis]

Complex scenario? Ha, we laugh at complex scenarios!

But seriously folks...

You haven't said what your output will be, but the following assumes WebHelp. First of all, you need to get straight with how your merged project would be maintained, generated, and distributed. Even your "core" project could actually be dozens of projects, or one project grouped within dozens of folders.

Using Peter's structure, you would have:

SOURCE FILES
Master project (with only a redirect to the start page in the "start" project)
...projects (folder only)
......Child "start" project (your "core" project?)
......Child2
......Child3

OUTPUT FILES (Generated to local machine, and Published to server location(s))
Master project (with only a redirect to the start page in the "start" project)
...mergedProjects (root-level output files)
......Child "start" project (your "core" project with your Home Page, etc.?)
......Child2
......Child3

• Each writer publishes to relevant folders (there is no need for "run-time" building), and Release Engineering grabs the root-level, "core," and Childx folders needed for whatever product build they're shipping. (Apex Systems gets core, Child 2, and Child 3, Brindle Systems gets core, Child 1, and Child 3, etc.)
• You might keep cross-references (external links) exclusively as Child-to-core links; that way, if the Child isn't in the specific build, there's no broken link, is there? If you absolutely need Child-to-Child, or core-to-Child links, assign multiple links at each instance with the same conditionals assigned as you're using for everything else. You could even create snippets to reuse pre-written, multiple-condition hyperlinks.
• As to different product and screen names, you might want to use variables for that.

Good luck,
Leon