What constitutes a project?

[dtmenges]

A single source newbie question

With Framemaker and e-Publisher, I have always thought of a one-to-on correspondence between a software title and a project. I have about five software titles that I support. Each title requires two targets, printed and on line. There are many common topics in addition to front matter boilerplate that could be done with snippets. So my question is this, is a project all of my topics that I need for software with multiple TOCs and targets?

Thanks for listening.

[lacastle]

Technically, a "project" is the filetype of a Flare file. You can one or many "software titles" per project, along with one or many TOCs and outputs. It all depends on how many files you have an how big your manuals are if you want to put them all in one project. It sounds like you have overlapping content, so one project might be a good option.

[Nita Beck]

My usual practice is to use global project linking.

I have one global project that contains common content: corporate images, publication boilerplate snippets, a master stylesheet for each of the types of publications I produce (e.g., help stylesheet, user guide stylesheet, training guide stylesheet, quick start guide stylesheet), a standard set or sets of conditional tags, a standard set or sets of variables (e.g., publication variables, as opposed to product variables). Here I also maintain shared topics, e.g., the topic regarding how to reach tech support, tech support hours, etc. I want to maintain that kind of stuff in one place only.

I then have one project per software product, with each project producing multiple targets (help system, user guide, quick start guide, etc.). Each project selectively imports items from the global project. I also have each project have its own product-specific stylesheet (for branding purposes) that is linked to the corresponding master stylesheet from the global project.

In one particular case, I have one project that actually supports two software products, because they share a lot of content between them. It made sense to maintain that shared content at the product project level rather than at the global project level.

Back to the global project, for one of my clients, I maintain a master glossary there (although not with Flare's glossary feature, but rather with a simple .htm file for each term). The idea is that there is just one place where terminology gets defined, across the entire documentation set. I conditionally tag each term .htm as to which product needs that term pulled into its glossary. Then, a given product-specific project *selectively* imports only those terms that are tagged for it. It works out really well.

My entire design philosophy boils down to this: Arranging my work such that there is only ever ONE instance of any particular thing that I need to maintain.

Hope this gives you some ideas.

[Nita Beck]

More thoughts...

I think actually that there is a danger to documenting multiple, *different* software applications all within one giant Flare project only in order to share some content.

If you haven't already discovered this, please be aware that when you generate a Help system, *every topic* in your Flare project will be output to the generated Help, unless you have conditionally excluded it. Say there are 50 topics exclusively for Software Product A and 50 topics exclusively for Software Product B and another 5 shared topics. If you don't conditionally exclude the Software Product A topics from the Software Product B help system, said help system will have 105 topics in it, not 55 as you might expect. And it doesn't matter that the TOC for Software Product B doesn't have those 50 Software Product A topics on it.

Of course, you can control all of this with conditional tagging. But many of us who have used Flare for a long time can tell horror stories of expected results for various combinations of conditionally including and excluding content.

I decided a while ago that if Software Product A and Software Product B have no need to "know about" each other, it was much safer that I maintain them in separate topics, and put their shared stuff in a global project. That way, I eliminate the possibility of accidentally outputting one product's content to another product's Help system.

[dtmenges]

Thank you for all of the answers. Converting to Flare has been an adventure but I think the end results will be worth it. For the first time in company history we are truly single-sourcing with reusable topics and everything is in source control.

[i-tietz]

That works as long as you need the same version of the standard files for each project. If not ...