Denise Kadilak, Blackbaud
Managing large amounts of content is never an easy task, but moving your organization from a linear authoring environment in Adobe FrameMaker to a topic-based environment in MadCap Flare will quickly swell your content library to overwhelming proportions. You can complicate this scenario even further by subtracting any possibility of a formal content management system. This is the situation the Blackbaud User Education team faced four years ago, when after 11 years working in FrameMaker, we decided the increasing demands on the documentation team required a move to a topic-based environment.
After testing several topic-based authoring tools, our team decided to go with MadCap Flare. The primary selling point was the Global Project Link functionality. We thought this it was a great tool to help us manage our expanding content library.
To make this work, we created a detailed workflow around the linking feature. The process allows us to import content and project files contained in one Flare project, known as the parent (housing our source content), into another project, known as the child (an empty project). During the import, we select which file types we want to include and exclude in the child project.
When we create a global link, also known as an import, in the child project, we take full advantage of the options Flare offers to help us control what content is imported:
- Automatically re-import before generating output
- Remove “stale” files (stale = files deleted, renamed, or moved)
- Specify what type of files you want to include (topics, images, any of the various template files)
- Specify what type of files you want to exclude
- Select specific files to include
- Add additional filters based on condition tags
In our workflow, we house all template files in a standalone template project (a parent project). These files include:
- Conditional text tags
- Variable sets
- Stylesheets (CSS)
All other projects, both child and parent, use the Global Project Link functionality to import this content, so when we make a change to any of our templates in the template project, all projects pull in the updated content. To establish this linked relationship, we create import files in all projects and point the imports to the template project (this is the Global Project Link setup). In the import file, we tell Flare exactly what we want to import into the project. For example, for the imports pulling in the template content, we tell Flare to include conditions, skins, variables, stylesheets, MasterPages, and PageLayouts.
We use a similar workflow for our source content projects. Our source content is stored in 44 different Flare projects, each project addressing a specific feature set in our software applications. For example, let’s say we have a Constituent Records, Administration, and Revenue Processing project, and we have two different software applications: A and B. Application A needs all three feature set projects; application B needs Constituent Records and Administration. In addition, the three feature set projects contain content specifically tagged for each application.
To address this scenario, we create two empty Flare projects, one for each application (A and B), and we import the template project into each. Next, to address the output needs for product A, in the product A Flare project we create imports for Constituent Records, Administration, and Revenue Processing, and we tell each import to include topic and image content and exclude all template-specific content. We also set the Import Conditions to include content tagged for product A and exclude content tagged for product B. For the product B output, in the product B Flare project we create imports for Constituent Records and Administration; we do not create an import for Revenue Processing. Again, we tell each import to include topic and image content and to exclude all template-specific content, and we set the Import Conditions here to include content tagged for product B and exclude content tagged for product A (See Figure 1).
Figure 1: Flare Project Example
You can take this is granular control even further. In addition to basing imported content on file types and condition tags, you can select the specific files housed in the parent project that you want to include in your child project. For example, let’s say product B’s project needs all content housed in the Constituent Records project but only four topics housed in Administration. The Constituent Records import stays the same as in the project B example above, but for the Administration import, instead of telling the import what file types to include or exclude, Flare allows you to view all content available in the Administration project and to manually select just the four topics you need (See Figure 2).
Figure 2: Manually Select Needed Topics
Although the Global Project Link functionality offers some nice content management options and robust content reuse between Flare projects, it also comes with a few headaches. My biggest complaint is the import files you create as part of the process occasionally hang and break. If your child project is small, and you are importing only four or five parent projects, this may not be a big deal, but we have child projects importing updates from up to 35 parent projects. In this situation, randomly breaking import files are frustrating and take time to fix.
Also, the process is complicated. It takes extensive planning, preparation, and maintenance. If you hurry at any stage, you will make mistakes, and the error messages provided when the process fails tell you nothing. Troubleshooting is not a pleasant task. As a result, managing this process is not for everyone.
Drawbacks aside, Flare is a great tool that provides you with several options. Although getting started can be overwhelming, it ends up well worth the effort. My best advice to learning the tool is to be methodical. Learning it involves a good deal of trial and error, and it takes time, but if you create solid processes and workflows to start, you will be happy with the results at the end.
- Madcap’s Global Project Linking Guide
- Feel free to contact me with any questions/observations/tips:firstname.lastname@example.org