5 products, 7 manuals cross-referencing - ideas?

[Eric Lachance]

Hey all,

I'm currently using Flare to write the documentation for a new product we're launching mid-June which makes 1½ months to write the whole doc - thankfully it's a really simple software. The doc is linear simply because we don't have time to start planning the single-sourcing part and because I have no experience whatsoever writing or planning doc - I'm new at this job, with only technical support experience in my belt (it helps, I understand the clients!)

Our long-term plan however is to convert our existing software suite's documentation into a single-sourcing Flare project (or projects), as all parts of the suite interact with others in intricate ways. Single-sourcing should help us keep data management to a minimum by putting everything in one place.

There are a few issues that I can already foresee however, and I'd like to start thinking about that now. Perhaps others have run into similar situations (not a whole lot of 5+ software suites exist and I'm assuming a small percentage of that use MadCap's suite, but you can't blame a guy for tryin'!) and can help me understand things and plan ahead.

Cross-Referencing
The first thing is cross-referencing. Two of the manuals that we have are dual-part - that is, we have a simple "user" manual and a more complex "reference and concepts" manual. The reason for separating it is purely financial: we are required to translate our user manuals in multiple languages, while the reference manuals (which is not "required" for software operation) can remain in English only. This means that at the moment, some pages and concepts are covered across both manuals, sometimes with the same content sometimes with a different writing style. Other concepts are in one manual or another. But most definitely, they cross-reference and have to retain those links across edits.

At the moment we are hard-coding the links in paths such as "/Documentation/EN/reference-guide/1234.html", and any modification of the html filenames causes links to break. They are separate source files, so changing one doesn't change the other. On top of that we don't exactly have control over the output filenames - they are stable as long as we don't delete and re-create a page, but the "1234.html" comes from the database ID for the page (it's in Drupal, using the Books module to output in PDF and webhelp-like format).

We'd like to be able to either link 2 projects together or to have a single project with tags and conditions... but that means we would have to put the conditions on the content files too, because I've noticed Flare will output any HTML file in the /Content folder regardless of whether it's being used in the TOC or if it's linked to.

Project Division
And then, where do you draw the line between what should remain one project and what should be a single project with conditions? Presumably, a "user" and "reference" manual from the same product would be one project, but then again their contents is 95% different with only some paragraphs and general concepts being shared. Cross-referencing would be the biggest reason to do this - if it can be automated.

5 Projects - One Source?
I was also wondering what can be done about using multiple projects. That is, if I have a 5-software suite that shares some contents between all manuals (either specific paragraphs, instructions, information about concepts, etc), is there a way to have a "Shared source" between all projects that would *not* be the /contents/ folder, where Flare could pick and choose the information it wants and needs when it builds the output? Presumably it wouldn't require conditions because it would not grab everything, just what it needs. Images, topics, stylesheets, etc. could be shared between projects.

This would also be used to store Marketing text (because we may ask marketing to correct some parts of a manual, and vice-versa) as well as the Training data (exercises, white papers, courses, etc) which we will eventually transfer to Flare. What we don't want is a single project with every single one of our project data (targets, TOCs, etc) synced via CVS - we'd much rather prefer keeping the sources and projects completely separate.

I'm open to any and all suggestions

[NorthEast]

My first suggestion would be to use a single project.
As it's a suite of related products with links/xrefs between them, then it'd make sense to try and keep it all together.

I'm not so sure about keeping the marketing and training information as part of the same project though, if you're just using the project to store files that aren't actually used in your outputs. If you do though, you can easily exclude them from the outputs.

We'd like to be able to either link 2 projects together or to have a single project with tags and conditions... but that means we would have to put the conditions on the content files too, because I've noticed Flare will output any HTML file in the /Content folder regardless of whether it's being used in the TOC or if it's linked to.

Yes, you'd have to use condition tags to exclude topics from help outputs, but with some good forward planning it may not be as difficult as you think.

One idea to simplify conditonal tags would be to keep the topics in separate folders, e.g. have a separate folder for each product and inside that have a 'user' and 'reference' folder. Then if you apply a separate condition to each folder, that way you can easily exclude groups of topics from the target - i.e. any combination of product, user or reference topics.
If you have some content that's shared and used in all of your outputs (e.g. copyright notice), keep that content in its own separate folder too, so that it's included in everything.

[Eric Lachance]

Having a condition on a folder is a good tip, thanks for that Dave!

Is it possible for the contents of a Flare project to be outside of it's default contents folder (external source)?

[NorthEast]

Having a condition on a folder is a good tip, thanks for that Dave!

Is it possible for the contents of a Flare project to be outside of it's default contents folder (external source)?

Not as such, anything that's going to be built and included as part of your output needs to be in your Content folder.

It's possible to add links (not xrefs) to files outside the Content folder (that you'd manage separately); but of course you'd have to check those manually, as Flare can't tell you if any links are broken.

If the 'external' content is in a Flare project, then you could use a project import to copy the required files into your project.