Strategy for Granular Modularity

[Stephen_B__Sealy]

I have a RoboHelp 9 project that documents the installation and configuration of a software package that can include add-in components. Currently, the core instructions and add-in instructions are all in one RoboHelp project, with condition tags to include or exclude steps for the add-in components. The add-in steps are in the middle of the software setup. That is, the user cannot install the core software, then the add-in components.

I have a new requirement to split the instructions into two RoboHelp projects: one for the core software and one for an add-in component. The idea is that the core project should not include any of the add-in instructions, but the add-in project can freely reuse information from the core project. (The projects have different owners.) The biggest risk in meeting this new requirement is that the user might incorrectly assume that he can complete the core installation steps, then look at the add-in instructions.

So far, my best idea is to set up a merged WebHelp project. In the core project, I'd use conditionalized snippets at the proper place in the step-by-step instructions to link to the applicable add-in information in the add-in project. (I think I can sell that idea as RoboHelp configuration, rather than combined content.) The add-in project will be pretty simple, with links to the core project.

Can anyone recommend a better approach?

[RoboColum_n_]

Hi Stephen. If I understand your requirement correctly you just need two versions of the same help file for each version of the install. If this is correct I can't see why you can't carry on using conditional build tags to include / exclude the relevant content. Do come back if I'm way off the mark. It wouldn't be the first time 🙂

[Stephen_B__Sealy]

The ownership of the projects is driving the requirement. The core software owner does not want to have add-in content in the core RoboHelp project. The software projects are cleanly separated (combined at build time), and the developers expect the same thing of the documentation.

[Peter Grainge]

If you set up merged help as described on my site, all the projects with content are child projects. In the generated TOC you would see Child 1 (your current main project) followed by Child 2 (the add-in).

That sounds like a solution as long as the owner is OK with Child 1 having links in the source that can be tagged out.

You would have to generate two setups.

The full merge would generate the parent (effectively a shell) plus the two children. In that build the links would be left in.

You would need a second web SSL in Child 1 allowing that output to be generated with the build expression to exclude the links to the add-in. That output would have no knowledge of the parent or Child 2 so it would give you content for the core product only.

---

See www.grainge.org for RoboHelp and Authoring tips

@petergrainge

[Stephen_B__Sealy]

Thanks, Peter. I had already experimented with the solution and sample project from your site. It should work perfectly for the reference topics, which are in a separate help system and require no core-to-add-in links.

For the installation and configuration topics, as I think more about the usability of the resulting help system, I'm considering a manual process that would be better for the reader and easier to understand for an author who inherits the project from me. The add-in RoboHelp project would contain all applicable topics. I'd import updated topics from the core RoboHelp system, as needed, then edit them to apply the add-in-specific changes. I might keep some HTML for the add-in steps in snippets to simplify adding them to the imported core topics.

[Stephen_B__Sealy]

To follow up on the solution: I am using the manual process described above. I created snippets that have the same names in both the core and add-in projects. In the core project, the snippets contain placeholder text, and in the add-in project, they contain real text. In both projects, I use a placeholder condition tag, which is used to exclude the placeholder text from the core output. With this scheme, the most reliable way to copy an updated topic is to have both projects open, and copy the updated HTML from a core topic to the add-in.

There was a glitch where links to bookmarks that were inside the snippets showed up as broken links in the project, although they were resolved properly in the output. I fixed that by linking to a generic bookmark that precedes the snippet.