You might know that Madcap introduced a project linking feature in Flare v.4. I’ve been itching to try it, and we got our chance when several of us were charged with providing a documentation set to a critical client that was receiving several of our products. The products had always shared functionality, but we previously documented those shared features in parallel. The time crunch of this project and the need to shine (it would be obvious and embarrassing if each of us presented our own takes on these features) pushed us to link up the Flare projects so that we could share that content and not make duplicate updates.
Some things I learned this week about linking up Flare projects:
You can move the linked files around without breaking things.
This might seem sort of basic, but it had me in a tizzy of concern before I finally just sat myself down and imported some topics. The topics come in at the same folder level they were at in the original project. For example, if the file path in the original project was “…Product/Menu/Option.htm,” when you import, the Project and Menu folders will be created in the receiving project, unless they already exist there. Then you can move the source files or the child files as much as you like. Flare will keep track.
You can pull in images, snippets, and condition sets by including linked files.
This feature just saves so much work. Flare uses linked images, and you can use a check box called “Include linked files” in the import file to import the images along with the topic. You can also bring in the condition sets and snippets that are used in the topics. If you want to make sure you don’t break links, and that you bring all the topics that are linked together, this is how to do it. I highly recommend bringing in your images this way instead of copying and pasting; otherwise you have to make sure you have the right folder levels in the Images folder of the receiving project, which is a silly pain. Plus, we created the original project from a Word import with embedded images, so many of the images were numbered rather than named. We would have had to hunt and peck for the images that were used in the shared files. Not fun for a large import.
By the way, you don’t have to accept all of the linked topics. Flare gives you a confirmation box to cherry pick files to include, plus you can filter by conditions. The conditions will override the linked topics feature, if you’re wondering.
If you create an import file but you don’t actually import anything, you could still overwrite files the next time you build a target.
We got burned with this yesterday. What happened was, I deleted a topic that I thought was redundant. Then I decided, well no, I would revise it instead. No problem, I thought, I’ll import that topic from a backup copy of the project. When you import, you can theoretically filter for such a topic by using a wildcard character (an asterisk) plus part of the file name, and I was curious to try that out. I had trouble getting the import file to find the topic, though, so I never did actually perform the import. I didn’t delete the import file because I thought I might use it later. I left it pointing at the backup copy, which was almost a week old. Gosh, that seems like a bad idea when I put it out there in black and white like that for all to see.
The next morning, when I attempted to build a rather small target from the project, Flare crashed repeatedly. I gave up and went to a meeting, and when I came back, my manager was in controlled panic, because for some reason the project had lost almost a week’s worth of work. “It’s kind of a big deal,” she said patiently to me on the phone from her desk, where the emails were flying between her and a network administrator. This was her way of saying that we were pretty screwed if we couldn’t figure out which wormhole the project had disappeared into. She’s such a nice person.
It took most of the day and a network restore to determine what had happened. It turns out that even though I never told Flare to import, since the import file existed, the files were updated anyway upon building. The lesson is this: either delete unused import files or don’t set the import file to automatically search for updates when you build targets. Oh yeah, and back up religiously, of course.
You can use a linked project to filter out unused files in a WebHelp.
We’ve got a WebHelp target that is significantly smaller than the primary target, yet all of the files that are in the project get included when we build the smaller WebHelp. This bloats the file size to the point that we can’t email the file. Since the WebHelp will be widely used by internal folk during implementation, that’s a problem. We tried a couple of the project hygiene tips that were listed on the Flare forum (clean the output folder, don’t build online targets to the same location), but they didn’t solve this issue. I think what we may end up doing is creating a new project for this deliverable and then importing the necessary files into that new project. We already have conditions set up for our various targets to supplement our TOCs, so theoretically we could use those to only pull the files for this internal deliverable.
Hurray, Project Linking
Overall, I am excited about the possibilities for reuse that this feature offers. Ours is a high volume shop, and we need all the help we can get in that area.
I’d love to know what you are doing with project linking in Flare. Do you have tips for me?
