Single Sourcing with MadCap Flare – Part 4 – Flare Project Import

In previous posts, I noted that conditionality and placeholders are the foundations of single-sourcing but described them being used in single projects. What if you need to use the same elements in multiple projects? For example, if you want all projects from different authors to use the same product_name variable?

You can create those elements from scratch in each project but that’s inefficient. Or you can copy the control files for these elements from a main project and paste them into the child projects, but what happens if the author of the main project adds a condition? The main project’s modified control files must be recopied into each child project; it’s easy to forget or to copy the modified control file into the wrong folder in the child project. And it’s easy for a child project author to change the control file so that it deviates from the one in the main project, with a loss of consistency. There’s a better way, the Flare Project Import feature.

Conceptually, this feature is simple and much like copying the control files from the main project to the child projects. The difference is that when you copy a file from the main, or master project, to the child, the Flare Project Import feature maintains a link between the master project and the child projects and redownloads the file from the master to the child if a copied file has changed in either the master or child project. Consider the example below.

You decide that all projects must use the same CSS and Copyrights topic. So, you create a master project, the top box in the flowchart, and store the CSS and Copyrights topic there. (You could use any project as the master. However, that project may contain files that don’t apply in this scenario and are just clutter. It’s usually less messy to create a new project whose only purpose is to serve as the master.)

The authors of the three child projects then link to the master and download the CSS and the Copyrights topic to their projects. All other files in the child projects are different, but the CSS and Copyrights topic are identical.

Now, the author of one of the child projects makes a change in the copy of the CSS downloaded to that child project. Or perhaps the author of the master changes the CSS. As long as there’s a difference in the CSS, or the Copyrights topic, or any other shared file between the master and child project, Flare will redownload the version of that file from the master project to the child project and overwrite the version on the child project when the author of the child project generates the output.

The beauty of this feature is that it ensures consistency across the projects in which it’s used. You no longer have to worry about the authors of the child projects changing the color of the h1 style in the CSS or changing the wording in the Copyrights topic; the next time they generate their output, their changes will be overwritten by the official version of the file in the master project.

Better still, this applies to any file in a Flare project. You get invisible consistency across multiple projects. I consider this one of Flare’s coolest features and yet one of its least well-known because, unless you took a class or called in a consultant, you’d never know that the feature even existed. And the name, Flare Project Import, doesn’t really say what the feature does.

A few tips if you want to use the Flare Project Import feature:

•       Create a separate master project and name it “Master Project” to avoid confusion. You can use any project as the master project, but this has two problems. First, using a real project as the master means that there will be a lot of files that have no use in the master/child model and are just clutter and potentially confusing.

•       Document the feature to avoid creating “zombie” projects. The term comes from an old client who asked me to investigate why the CSSs in his group’s Flare projects kept reverting to some standard format even though the authors were deliberately modifying their CSSs. As the client said, it was as if the CSSs had become zombies. The problem was that a year earlier, an author had set up the Flare Project Import feature but didn’t document it, then left the company. So the feature was working perfectly but no one knew why or what to do about it. Avoid this problem, and spare yourself the need to call in a consultant, by documenting the project.

That’s it for Flare Project Import. Next up – conditionalized styles and CSS variables.