Multiple projects w/cross-project links, or single project

[sdriggars]

Is it better to have multiple Help projects as individual projects, or to combine them into a single project?

I am working with three other writers on a Flare project with WebHelp output. The source files are stored in Team Foundation Server. Currently, we are using version 3.1, but shortly will be moving up to version 4--although we'll move even faster, if it will solve our problem.

The product we are documenting has several main modules that operate somewhat independently but also have related functionality. Most modules are delivered together as part of a package, but some are optional. We currently have a Help project for each module, and each writer is responsible for multiple projects. Each project has its own TOC, index, snippets, variables, and glossary. The glossary and some of the variables and snippets are the same for all the projects and could easily be shared.

There are some topics that are common to the multiple modules. In addition, the optional module projects may need to link to some of the other module topics if any of the optional modules are installed.

As a result of this, we are exploring creating a single Help project that is made up of all the currently separate projects. This would allow us to have a single TOC, index, snippet file, variables file, and glossary for the combined project, and would also simplify the linking within the project.

We would still have separate projects for the optional modules. (We considered using one project with conditional text for the optional modules, but the output combinations seemed unreasonable—currently, it could be up to 16 different outputs, and it would grow exponentially as we add more modules.)

However, I now see that with Flare V4, we can import topics, snippets, and style sheets from one main project to multiple other projects using the Global Project linking feature. Might this be a better option? Some have told us that topics don't import across projects well, if at all (we haven't been able to figure out how to make it work yet), and that is one of the main issues we need to solve.

We need to keep our projects as low-maintenance as possible, and also need to consider potential conflicts with source file handling. Most importantly, we need to deliver Help that is useful to our customers. Do you have any recommendations for this situation?

[doc_guy]

I'm doing a combination of both things you discuss. I'm using global project linking, and I'm creating several separate, but related outputs from a single project.

I set up my project this way because there are some corporate files that I want to be the exact same in every project. These include the style sheet, page layouts, master pages, and skins, to name a few. These files reside in the master project which I link to all my separate Flare projects.

Then I have a flare project that currently has 21 different targets, but tomorrow may have 22. This project builds a variety of books and web helps; some are 200 printed pages, and some are only 30 printed pages. There are topics that are shared, and snippets that are used across projects.

Some things to be aware of:

First, if you decide to do the gargantuan project, like I have: recognize that you will have to use conditions effectively for this to work well. This means conditionalizing topics that you only want to be in one project but not linked to another project. Basically, on a file-by-file basis (or directory-by-directory, if all the files in the directory share the same properties) you have to specify which projects the files are used by. This is important because when you build a web help target, you get all the files in the project unless a condition explicitly excludes them. When your users use the search feature, or when they use the index they will see results for ALL TOPICS in the project, regardless of whether or not they are in your TOC. The way to avoid this is to use conditions properly, and exclude conditions that don't apply to a given output.

Second, if you decide to go with the global project linking: be aware that updates to the master project have to be done in the master project. It seems obvious when you state it, but it is kind of a pain to switch to the Master project every time you want to modify a tinsy part of the style sheet. You can't save the change in your local project and have it link back and update the master project. You can open a second instance of Flare from the Start menu, and then you can open the master project and keep both projects open, but this can be a resource hog, especially if you are just barely meeting the memory requirements for Flare.

I'm not trying to talk you out of either option. I use both every day. I just thought you should be aware of some of the gotchas for each of the two options.

[doc_guy]

Oh, and if I haven't welcomed you to the forums already, then let me do so now: Welcome to the forums.

[sdriggars]

Thanks, Paul. I appreciate your input.

The real issue I need to solve is whether I can share topics across projects. For example, I may have a series of topics on security that will apply to multiple projects, so I want to store those in a master project but have links to those topics from the sub-projects. Is it possible to do that?

[SteveS]

The real issue I need to solve is whether I can share topics across projects. For example, I may have a series of topics on security that will apply to multiple projects, so I want to store those in a master project but have links to those topics from the sub-projects. Is it possible to do that?

I called for this feature from Flare 1.x and its been answered with the master project feature in Falre 4.

If you are using Flare 3.x or earlier you can either keep the common topics in the 'my templates' structure and add it to the project when you create the project using a template or using the add topic dialog, choosing the topic from the user templates.

I created new projects for my shared topics. If you are creating online help you can merge the projects at build time, but this doesn't work for printed documentation.

Beacause I was creating manuals at the same time as online help I had to use a didfferent approach. I copied the topics from the shared topic projects. Each of the topics had a remark at the top, identifying it as a shared topic and saying where it was used. That way, if I made a change I could find other places where the topic was used and updaye tthem as well. I had an Excel spreadsheet to track common topic usage.

It worked, but I was so happy to see the master project feature in Flae IV. (Except I don't work there anymore, so I don't need the feature at the momemnt...)

[NorthEast]

The real issue I need to solve is whether I can share topics across projects. For example, I may have a series of topics on security that will apply to multiple projects, so I want to store those in a master project but have links to those topics from the sub-projects. Is it possible to do that?

You can certainly use topics from a linked project. Say you had your topics about security in project A, you could import those topics into project B using project linking. As for links, you could have links from topics in project B to those in project A, but you couldn't have links from topics in project A to project B.

My general advice would be that if you have a lot of links between the topics in your modules, then keeping them in a single project will be a lot easier (than using project linking, or project merging).

If you go down the route of using one single project, then do think carefully about what outputs you need, and then work out what condition tags (or combinations of tags) that you need to use to generate those outputs.

Also, your number of outputs shouldn't be any more complex than it already is - if you have 16 targets in a single project or 16 targets spread across a number of separate projects, then you still have 16 targets to look after.

[sdriggars]

Thanks to Steve and Dave for their insight. We still need to do some testing to figure out how to make the project links work. I think the links will need to work both ways, so a single project may be our best option. We've gotten push-back from development and install regarding having multple outputs that are installed dependent upon the customer's install profile, so that affects our decision, as well.
Thanks again!

[crdmerge]

Current RH X5 shop, evaluating Flare (again - the Subsystems/Content folders were out of control in V1 beta, so I gave up on it because the inconsistency would create CSH problems; however, my first look at V4 doesn't seem to show much improvement).

42-project merged WebHelp (final help always contains all projects, all topics, no conditional builds), 7 writers, ~2400 topics, minimum ~1500 "external" links, individual PDFs of each project (no links required) needed when each version ships.

INITIAL CONCERNS AFTER IMPORTING A MASTER AND ONE CHILD

How is GPL actually implemented (local machines, servers, with or without Team Server, etc.)? Whereas RH projects must be edited on your local machine, can Flare projects be edited on a server? That is, how does a doc group take advantage of the variables/snippets/master pages features?

Why is Flare improperly importing some of my tables into the XML Editor, mangling them for the Primary WebHelp target, and then mangling them further in a subsequent Printed Doc target?

Examples:
As part of a two-column table, col1 has a single merged row, and col2 has the relevant 4 rows of content.

• In the XML editor, col2 row1 is fine, but col2 row2 thru col2 row4 are squeezed into a narrow single-word column.

• In the WebHelp output, col2 row2 thru row4 are again squeezed into a narrow single-word column outside and to the right of the main table!

• In the Printed Doc output, col2 row1 content is incorrectly bolded (like col1), col2 row2 is empty, and col2 row3 and col2 row4 have disappeared (along with their content).

As part of a three-column table, col1 has a single merged row, and col2 and col3 both have the relevant 6 rows of content. In the .doc file, col2 becomes a single merged row with no content, and col3 now contains the content from col2; the previous col3 content has simply disappeared! In addition, borders are randomly missing (no set pattern - some left, some top, etc.).

I understand that converting projects (even from the same product's version to another version) will require some amount of cleanup, but since our 42 projects contain at least 2500 tables, this importing anomaly becomes problematic, don't you think?

Oh, and by the way, why was my only option for a language on this forum "British English"? I'm on the other side of the pond...

Thx