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.

Single Sourcing with MadCap Flare – Part 3 - Placeholders

Another Flare feature that supports single-sourcing is placeholders, which Flare offers in two forms – variables and snippets. Placeholders let you insert the same content in multiple places in a project, such as multiple topics, and automatically change that content everywhere with just a few mouse clicks.

For example (from the introductory post), let’s say that you’re documenting a new product whose pre-release code name is Longhorn. You write the word “Longhorn” in hundreds of places throughout the documentation.

Then, just before release, Marketing changes the product’s name to Vista. You now have to search the documentation for all instances of “Longhorn” and change them to “Vista”. It’s easy – just do a search and replace.

But what if you misspelled “Longhorn” several times? A search and replace won’t fix that. You could do a fragmentary search and replace – search for “Long” – but that would give many false hits. 

Or, let’s say that you have to repeat the same set of steps in multiple topics. Easy – type the steps once, then copy them and insert them in the appropriate topics. But what happens when one of the steps changes? You have to find each insertion and change it. But how do you know where you inserted the material. You might keep track of the insertions but that calls for an unusual level of management. You could again search for the insertions but that might again bring up false hits. Placeholders are a solution in both cases.

Variables

The simplest placeholder is the text-only variable. In the first example, rather than typing the product’s name over and over again, you’d create a variable called, perhaps, productname, and set its definition (its value) as “Longhorn”. You’d then tell Flare to insert the value of the productname variable wherever you wanted the word “Longhorn” to appear in a topic or other file.

Then, when Marketing changes the product name, you’d simply change the value of productname from “Longhorn” to “Vista”. Flare then automatically changes the “wording” everywhere you inserted the variable. You don’t have to keep track of the insertions – Flare does that.

Variables are easy to create and use. What can be tricky is defining them. For example, what do you do if you need to use a variable as a possessive – if you want to say “Longorn’s features include…” Do you create two variables called productname and productname_possessive with values of Longhorn and Longhorn’s, or do you use the single productname variable and type “’s features include…” and insert the productname variable in front of the “’s”? Either approach works; you just have to define which approach to use and get all authors to agree.

Flare stores variables in a file called a VariableSet, with an extension of flvar, accessible from the Project Organizer pane. You can create multiple VariableSet files if you want to categorize multiple variables or simply break multiple variables into smaller groups.

Several points regarding variables:

• Variables usually have one value but you may need more sometimes for different outputs. For example, you might be generating US and Canadian outputs and have a variable called country. You specify that the value of that variable is US. But if you’re generating Canadian output, you’d want to change the value to Canada. You can override the US value on the Variables tab of the Target Editor but it’s a good idea to minimize the typing needed to specify output settings. The solution is to create the country variable, specify its value as US, but then click the third icon, Add Variable Definition, on the VariableSet Editor toolbar. You’ll see a second instance of the country variable, greyed out, and can now type the additional value, here Canada.
• How then do you tell Flare what value to use for a particular output target? On the Variables tab of the Target Editor, there’s a dropdown link to the right of any variable that has multiple values. Click that dropdown link and select the desired value.

• In addition to the standard variables, you can also specify date and time variables. One common use is to add a variable that specifies when the output was generated and that’s automatically updated. Click the second icon, Add DateTime Variable, type the name, such as Generated On, then click in the Definition field. When the Edit Format dialog box opens, type the format – click the I icon for help – then specify when to update the variable.

Snippets

Snippets are similar to variables but more powerful because they can contain anything you’d enter in a topic – text, lists, images, tables, links, formatting, and so on – including variables. In example two above, rather than typing the steps, copying them, and pasting them into the appropriate topics, you’d create a snippet called, for example, task1_steps. You’d then insert the task1_steps into the appropriate topics. When the time came to change one of the steps, you’d change it in the snippet itself. Flare would then automatically change the “wording” everywhere that you inserted the snippet. Again, you don’t have to keep track of the insertions – Flare does.

Each snippet exists in a separate flsnp file that’s accessible from the Resources folder on the Content Explorer. (You can put the snippet files anywhere you want within the project’s structure. I just find it simplest to store them in the Resources folder.)

Several points regarding snippets:

• You can create text snippets and block snippets. A text snippet consists of one paragraph of text or less. If you insert a text snippet on a new line or in an existing paragraph, it keeps its structure as a line of text. A block snippet consists of two or more paragraphs of text or other element followed by a return, such as a graphic. If you insert a block snippet on a new line, the snippet retains its paragraph structure. However, if you insert a block snippet in an existing paragraph, the block snippet paragraphs become run together.

• As noted above, a snippet can contain a variable. However, because you can assign conditions to snippets and variables, it’s possible to have a snippet to which you’ve assigned a condition to be excluded for a particular output but that contains a variable to which you’ve assigned a condition to be included for that same output. In such a conflict, Flare will default to an include so it will display the snippet because it contains the variable. The problem here is a management one; you’ll be wondering why that snippet displayed in the output when you thought you’d excluded it. Keep careful track of how your snippets, variables, and conditions interact.

• If you have numerous snippets and need to modify one, it can be hard to pick out the right one. The shortcut is to find one instance of the snippet, right-click on it, and select Open Link. This immediately opens the correct snippet file, saving you the trouble of hunting for it.

• Snippets can solve one limitation of variables. What if you want to end a step in a procedure by telling the users to “Press Enter.” You might create a variable called actionstep, for example, whose value is “Press Enter”. But what if you want the action step’s value to be “Press the Enter icon” followed by the actual Enter key icon. A variable is text, so that won’t work. However, you could create a snippet called actionstep that contains both the text and the icon.

As with conditions, common problems with placeholders are in design and management. We often give placeholders names that are not clear. The result? Other authors using the same set of variables or snippets won’t find what they’re looking for and wind up creating duplicates, which complicates project management. A related problem lies in not documenting the rules and logic to use if an author really does need to create a new variable or snippet. As with conditions, when you leave and a new author comes on the project, they may send the project off the rails because the lack of documentation makes it easy to make mistakes.

That’s it for placeholders. Next up – Flare Project Import, one of Flare’s coolest and least-known features.