In his previous post, Joe Cheverie discussed the business problem at his previous company that required splitting a massive MadCap Flare project into smaller child projects. This post will cover how these child projects relate to one another, and how to pull content from each of these child projects to create a converged output.

Importing Global Files

The parent repository project contained our common elements like conditions, page layouts, stylesheets, snippets, and variables. This project also contained an initial TOC and target definitions that could be leveraged in the project for unified output. This parent project ensured each of the child projects would have the same global elements among our Flare projects to provide a unified look and feel.

We set up an import file within each of the five child projects to import common elements from the parent project to the child projects. As an example, this import file was created within our Framework project:

Generating a Consolidated Output from Multiple MadCap Flare Projects

We had to ensure the files from the parent project were imported to the child projects regularly to avoid conflicts in Team Foundation Server (TFS). At the beginning of each workday, each writer on the global team would get the latest files of the parent project on their local system. So when they opened a child project afterwards, the writer would run the “Link_to_Master” import file located in each child project.

To ensure a consistent process, the writers would place the child Flare projects on the same hierarchical level in Windows Explorer as the parent project. This made certain that the import file located in the child projects would be the same for all writers on our global team. In addition, we kept the parent and child projects on the same hierarchical level so writers would use the same relative path on global files imported into the child projects. The writers would then double-check that the following settings in the import file were enabled:

  • Auto-reimport before “Generate Output”: This was enabled to ensure we pulled in any updated changes in case other writers were working on content in the parent project.
  • Delete stale files: This option was enabled to remove any files that were not used in the output.

When those settings were confirmed, the writers would click the Reimport button to import the latest content changes from the parent project.

Creating Converged Output from Multiple Flare Projects

Once the child projects were synchronized with the correct files, we had to determine how best to produce coverged output from all of these child projects.

The key concern was to avoid the initial performance issues we incurred. Therefore, the solution was to create an unbound master Flare project that would handle all of the content from the child projects.

While this resulted in an inverse workflow from splitting up the original Flare project, the converged project allowed us to build the consolidated content without enduring the previous performance issues.  This was accomplished by not binding the converged output to TFS, and by having one writer (instead of a team of 20 writers) building the output on this master project. We created import files in the converged project to pull updated content from all of the child projects. These full imports were initially done to ensure relative integrity within cross-references between the consolidated child projects.

Generating a Consolidated Output from Multiple MadCap Flare Projects

The TOC of our online Help was structured based on each of the child projects we created. We merged the TOCs of our child projects into the converged project to ensure we kept the integrity of the TOC structure intact. This was done by linking the specific child project and its corresponding HTML5 target to ensure we pulled in any content or structural changes. This merged TOC and the corresponding online Help target existed only in the converged project.

Once the TOCs were merged within the converged project, we could now build our output.  In this case, it was the online Help for our Workforce Management software system.

When the converged online Help output was successfully built, we would publish the online Help. We would also check this output into TFS for versioning purposes in source control. The output was checked in manually so we did not have to bind the entire converged project to TFS.

Achievements and Lessons Learned

By creating child projects from the Flare project originally migrated from Adobe® FrameMaker®, we were able to achieve the following:

  • Alleviate ongoing performance issues in the large unified project
  • Rebind the child projects through Flare to TFS source control
  • Synchronize global project elements among the child projects
  • Create singular output from multiple Flare projects

We learned from our migration process was to split up our content into intuitively segmented child projects rather than trying to force all of our content into one Flare project. Another important lesson was to create projects based on which writers would be contributing to certain modules. By designing the child projects with these factors in mind, it allowed us to migrate subsequent content to Flare without any of the performance issues that previously hindered us.

About The Author

Joe Cheverie

About Joe Cheverie

Joe Cheverie is a seasoned professional with 15 years of technical experience and expertise in the IT and software industry. As Technical Writer for MadCap Software, Joe supports the technical communication team, and is responsible for the creation and delivery of content for the entire suite of MadCap Software products.

Last Modified: December 20, 2017

This entry was posted in MadCap Flare, Tips & Tricks. Bookmark the permalink.

Comments

  • Albert Needell January 9, 2018 at 10:16 AM

    Good report, thank you. How did you handle cases (such as variable sets) where files in the global project required modification in the child projects? Re-importing will overwrite the user’s changes, which can be a problem.

    • Joe Cheverie Joe Cheverie January 9, 2018 at 12:28 PM

      Hi Albert-

      Typically, our team made sure that the writers modified any variables (or variable sets) strictly within the parent project. By adding and editing variables only at the parent project level, it would prevent any variables from potentially being overwritten within the child projects, as you pointed out.

      One exception to this were the variables in the targets of the child projects. For example, in our reports child project we would specify the title of the reports guide for the PDF target . We would provide a generic value of the title in the parent project, and only specify it within the Variables tab of the target.

      Hope this helps. Please let me know if you have any additional questions. Thanks for taking the time to read and provide feedback!

      Joe

  • Albert Needell January 9, 2018 at 4:02 PM

    Thank you, Joe, that does help. It would be very nice if Flare allowed us to merge individual variables from the global project down to the child project. Right now, we need to reply upon each project periodically adding new variables. Thank you.

  • Marion Verhaegh January 9, 2018 at 9:57 PM

    Good information! I’m a ‘lone writer’ and have done a very similar thing for my projects because of size issues (slow internet connection). Additional to stylesheets, snippets, variables, pagelayouts, masterpages and a host of images I have included topics that need to be in all child projects in my ‘Shared’ project. Some topics that need to be in more than one, but not all child projects are also in my Shared project and have been conditioned in and out. It’s good to read that my thinking is along very similar lines to yours. My targets are CHM and PDF. You’ve inspired me to experiment at some point with consolidating all child projects into one. Thank you for this information – I will keep it safe somewhere.

    • Joe Cheverie Joe Cheverie January 11, 2018 at 3:55 PM

      Hi Marion-

      Thanks for your comment, appreciate you taking the time to post it. We also did have a few topics that were shared among our child projects, it sounds quite similar to your project structure. Conditions were definitely used extensively in our parent project in relation to our targets, and it certainly helps to manage those elements downward to the child projects.

      Thanks for sharing your experience, and good luck!

      Joe

  • David Schor January 11, 2018 at 3:50 AM

    Hi Joe, did you use Tripane or TopNav skin in your HTML5 output (not sure if the linked projects are supported by TopNav)?

    • Joe Cheverie Joe Cheverie January 11, 2018 at 4:08 PM

      Hi David-

      Thanks for your comment. We used a Tripane skin on our HMTL5 target. However, I ran a quick test with a TopNav skin selected on an HTML5 target, and I was able to run the import file from the parent project to the child project without any issue. But if you experience issues with a TopNav skin on your target, please let us know.

      Joe

  • Anita Burstein January 11, 2018 at 5:46 AM

    Hi. I’ve built a similar structure with one main difference. When we imported content directly from each child project to the parent project, I found that the timing was sometimes off. One writer might be finished with their content a week early and ready to start on the next release so whenever I imported from ‘live’ projects I didn’t know if I was getting a draft, the current updated content, or content for the next release.
    Problem solved: Each writer exports their final content to a central location that is not bound to TFS. This ‘freezes’ the content so that the writer can immediately start work on the next release. They export just a target with all the conditions and variables set. Then my parent project has a TOC with of all the projects. Each entry points to one of the exported projects and uses “Select Flare Project and Target for runtime merging”.
    The advantages are:
    1. I always have only the content that the writer wants me to publish.
    2. Using Robocopy, I copy all the css stylesheets into the exported projects so that the final version always have the updated styles.
    Good luck!

    • Joe Cheverie Joe Cheverie January 11, 2018 at 4:20 PM

      Hi Anita-

      Thanks for sharing your experience. I agree that having the TOC entry point to the specific Flare project and target is quite beneficial when consolidating output from multiple child projects. While we typically were able to avoid conflicts due to simultaneous work on multiple releases, I can see where having a central non-bound repository would alleviate any potential conflicts among a team of writers.

      Thanks for providing your feedback, and best of luck to you as well!

      Joe

  • Christopher Moore January 25, 2018 at 2:03 PM

    Hi Joe,
    Interesting article and great information. My team has a project structure that uses “runtime merging,” or, project merging when building and publishing (as Anita refers to above). We do this so that we can publish individual subsystems/projects at separate times (and avoid having to build one large project). Flare documentation indicates that this structure setup is not compatible with TopNav. The note at the bottom here indicates so.
    http://help.madcapsoftware.com/flare2017r3/Content/Flare/Output/HTML5-Output/HTML5-Top-Navigation-Output.htm
    Is “converged output” in your diagram above suggesting this merging? If so, it seems you can use TopNav in this scenario, as you suggest. Or am I talking about two different things?
    By the way, we use git for version control.
    Thanks.

    • Joe Cheverie Joe Cheverie January 29, 2018 at 11:44 AM

      Hi Christopher-

      Thanks for your response. I did a test build on the converged output using a TopNav skin, and I was able to produce the output without any issue. I’ll take a look at that note you referenced (thanks for providing the link to it).

      Yes, the converged output is the merging of the child projects into the final output. In this instance, we merged five child projects to produce the converged output.

      Hope this helps, please let me know if you have any questions. Thanks for taking the time to reply on the blog post.

      Joe

Have Something to Say?

Your email address will not be published. Required fields are marked *