Joe Cheverie is a technical writer at MadCap Software, with extensive experience writing installation guides, online Help systems, and user guides for software products. In the first part of this two-part series, he describes his experiences and the challenges of creating one output from a single project combined from multiple Flare projects.

Prior to working at MadCap Software, I was at a company that migrated their Help content from Adobe® FrameMaker® to MadCap Flare. The Help content was part of a software system that handled common workforce management functions: employee scheduling, user management, and reporting.

Identifying the Business Problem

We initially migrated all of this content into one massive Flare project. This project comprised nearly 100 individual user guides, in addition to the online Help targets.  Once the migration was completed, we bound this large project to Microsoft Team Foundation Server (TFS) source control.

However, as we started updating our content in this Flare project, we were immediately beset with three performance issues:

  1. TFS Binding: As we only had one dedicated TFS server that was located in the Tel Aviv office, we experienced serious latency issues whenever we had to check in our changes in the Flare project to source control.
  2. Size of Flare Project: Given the amount of content, there was an additional lag when trying to launch the Flare project.
  3. Multiple Writers Accessing Same Project: We had a global team of about 20 writers that would try to access this project at the same time. In addition to causing a performance hit, we also incurred numerous conflicts when trying to check in our changes to source control.

These issues brought our productivity nearly to a standstill.  How could we alleviate these performance issues so we could do our work in a timely manner?

The Design and Planning Process

It quickly became apparent to our writing team that we would have to split up the large Flare project into more manageable pieces. We felt that splitting the large Flare project into smaller child projects would allay our performance issue concerns.

But before we could split the large project into smaller ones, this brought up an issue: how would we circulate the standard elements of our Flare projects among the newly created child projects? It became necessary for us to create an additional project that would house our common conditional sets, page layouts, stylesheets and variables. Therefore, we created a parent project that would be the repository for all of these entities.

Our parent project included everything that was needed for the deliverables, except for the specific content located in the child projects. We structured the child projects with the content size and the number of content contributors in mind. Each child project concentrated on certain aspects of our content, such as product, development team, and location. For example, we created a child project named “Reports” that contained the procedures for creating and running reports on the software system. There were three primary writers assigned to the reporting module, so it made sense to create this project.

When creating the other child projects, we took into account functionality that could be self-contained, like reporting. We also made sure that the child projects would be divided among the team writers equally, so there were no more than a few authors on a child project at any time.

Once those child projects were created, we set up an import file within each of them to import the variables and other global elements from our parent project. This was done so that we could keep all of the global files synchronized between the parent and child projects.

In total, we created five child projects to cover the various modules of the software system:

  • Workforce Management: Managed calendar and scheduling functions
  • Reports: Described reporting and analytic features
  • Performance Management: Documented employee scorecards for training purposes
  • Getting Started: Covered the basic functionality, including dashboard features for the system
  • Framework: Handled adapters and third-party software integrations

generating a consolidated output from multiple madcap flare projects

The child projects were created with the size and scope of the underlying content in mind.  While we were not trying to achieve an exact match between each project, it was important for each project to have a relatively equal size.

After creating our projects, we needed to figure out how to pull together converged output from each of them. In the next post of this series, I cover how we were able to do so, as well as the benefits of the overall process.

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: January 23, 2018

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


  • Stephane December 13, 2017 at 3:43 AM

    Thank you very much for sharing your experience. We are facing a quite similar issue with our online help documents; i.e.; splitting a large Robohelp project into small Flare projects which are used within a parent Flare project.

    Look forward to read the next part of the article.

  • Stephanie M. December 21, 2017 at 9:14 AM

    Great information to keep in mind. I currently have one project with multiple child projects within it. I am curious to know if you use one stylesheet for all of your projects, and if you house the stylesheet in the parent project and can link it between projects, or if you have separate stylesheets. Also, if there is a need for the same snippets, images, cross references, etc. in all projects, is there a way to reuse them or link them?

    I don’t currently have a need to create separate projects and do not have experience with it so just wondering from a newbie perspective. Thanks!

  • arthur January 23, 2018 at 10:27 PM

    Thanks for the sharing Joe. We are in the planning stage of Flare migration, and also thinking about how many projects we need to create for our doc set, so this article is very relevant. About the first performance problem you mentioned, do you know why the latency is bad for large projects (we use TFS as well)? Even if there are thousands of topics in the project, we normally just (at least specifically) check in a few topics one time. I don’t quite understand why the network traffic would be huge for this scenario, maybe because Flare does auto-checkins for many supporting objects in the background? Thanks

    • Joe Cheverie Joe Cheverie January 25, 2018 at 9:44 AM

      Hi Arthur-

      We found that having all the global elements of the project side by side with the content of our child projects was cumbersome. Whenever we tried to update either a master page or a topic in the singular bound project, we found that we always suffered a performance hit. Once we split those projects up and ran imports between the parent and child projects, our performance greatly improved after splitting up those projects.

      There are always other variables at play in an environment. For example, hardware issues on a server hosting source control (e.g. TFS) could be contributing to the performance issues. Network connection speed could also be a potential issue as well. Bottom line, we isolated the problem to the point that it made sense to split up our projects.

      Hope these blog posts are helpful while you plan the number of projects you need for your documentation set. Thanks for your feedback!


Have Something to Say?

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