Sharing chapters across multiple projects

[chrisalley]

I'm documenting five applications with their own self-contained HTML Help files. The Help files are essentially online books with about 20 chapters each. However, many chapters are reused in various applications, with minor differences. Instead of copying a common chapter four times, I'd much rather have a single master version and pull it into each of the separate application Help projects.

I'm fairly new to Flare. I've talked to a couple of people, and here's what what I've gotten so far. I'd appreciate comments or suggestions from more experienced users.

1. For each of the common chapters, create it as a separate, standalone Flare project.

2. Make each of these common chapters self-contained, with no links outside the chapter.

3. For common chapters that have minor differences between the five applications, handle those with conditional text.

4. In the Flare project for each individual application, link a TOC book to the standalone project for the common chapter.

5. Make sure all the separate Flare projects use the same CSS.


As I wrote this, several questions came to mind:

* Do index entries in the common chapter show up in the resulting Help?

* Within an application, can you point context-sensitive links at a topic in a common chapter?


Is this really the best way to reuse chapters? Or is there a better solution? Sorry if this is similar to some existing postings.


Thanks,
Chris

[wclass]

Hi Chris,

We probably all have a different opinion of what works best, so don't take this as set in stone - it's just one person's experience. I'd take a different path than the one you have suggested so far and have one project that generates all the required targets with conditions. I tested this a long time ago (pre-Flare) and found merging CHMs very fiddly and hard to handle. I did have problems with CSH (context sensitive help) - would have had to do some manual processing, but indexes always worked. I have a few projects with several output targets, and I find conditions easier to manage than merging.

Now it really will depend on how often you need to update this information, but I think separate projects are harder to maintain, and your 2nd point, about no links, is just too restrictive. Of course, if you are likely to get more apps you'll need to re-assess. I think 5 outputs is manageable in one project.

We have a few projects here that have different installations for different roles, so there is common information plus a lot of differences. I have one project with 4 targets, including a CHM, several webhelp versions, and a Word document. The online stuff all has CSH, and I have to get different header/alias files for each installation. I have a separate TOC for each target. But being one project there are no issues with style sheet, master pages, snippets, condition sets, variable sets, glossary, destinations, etc. In fact, for me, one of the advantages of Flare was the way targets are organised with separate TOCs and conditions - I think the single project view works much better.

[chrisalley]

Margaret,

Thanks for your reply. I appreciate it. I need to take a few days and think about this some more.

The five applications share only about 30% of their chapters...some more, some less. Each application is pretty big. At first thought, the idea of creating all five from a single project kind of scares me. I need to think about how I could make that work.

Thanks again,
Chris

[KevinDAmery]

I agree with Margaret that using one large project would likely be the way to go. 30% shared material may not sound like much, but if you have to update your documentation at some stage that means you would have to update each of those shared topics in 5 separate locations (or do a lot of copy / paste operation, hoping like heck that you keep straight which project has the correct material for each shared topic... makes my head hurt just thinking about it).

Basically, what you would do is apply a condition to each topic based on which application it applies to (eg. App1, App2, App3, etc.). Any topics that appear in multiple help systems would either have no conditions applied (if it's the same topics that appear in every doc set) or a combination condition (e.g. App1_App2 for a chapter that appears in both application 1 and 2 but not in the others).

Step two is to make a TOC for each application, including the appropriate topics.

Step three is to make a target for each application that uses the appropriate TOC, and is set to Exclude any conditions that are not intended to appear in that document set.

[LTinker68]

30% shared material may not sound like much...

And it's not just the material. It's the stylesheet, the skin, the variables, the help title, etc. If you want to add a style, it's must easier to do it in one stylesheet than to open five projects and copy the style into each stylesheet. And you can't copy-and-paste changes to the skin, so you'd have to repeat the steps to make the change in each skin.

Definitely easier to keep everything in one project.

[doc_guy]

Another vote for keeping it all in the same project.

In my Flare project, I'm writing content for three separate products, but I've only got a single Flare project, for all the reasons previously mentioned in the thread. In some of my projects, I have virtually no topic overlaps, but I have one source for stylesheets, masterpages, skins, etc.

[forfear]

Mr Mike's post on Project Size might be a helpful little sidenote

http://madcapsoftware2.wordpress.com/20 ... ject-size/