MadCap Flare is a very powerful tool. It has so many features and options it can be a challenge determining the best place to start, particularly on a project level. New Flare users often jump right in and begin importing or authoring content. But without proper planning, a small issue in your project now could turn into a much bigger problem later on that ripples down to future projects.

The following best practices are recommended for any new user that’s starting a Flare project, or for experienced users who need a refresher.

1. Use Version Control

In short, a version control system stores the main copy of the project on a server. Individual authors can then download a copy of the project to their local PCs. The authors can then make changes on their local copies of the project and upload those changes back to the main, or master, copy on the server.

Individual authors still have to coordinate in order to avoid changing the same material, but the version control system will track the changes and warn of any conflicts. Version control systems offer additional benefits, such as the ability to “roll back” to an earlier version of the project and the ability to highlight differences (“diffing”) between two versions of the same file.

Flare supports most major version control systems natively, including Subversion (SVN), Microsoft Team Foundation Server (TFS), Git, and others. MadCap Software also offers its own cloud-based system called MadCap Central, which combines version control features with project management features.

While you don’t need version control to write documentation, it’s a great way to ensure that your work is backed up, in the case of an emergency.

2. Use a Parent-Child Structure

The parent-child project structure, created using the Flare Project Import feature lets you create one project that you designate as the “parent” project and that contains files like the CSS and common topics that you want to share across other projects.

You then create the “child” projects, link each child to the parent, and copy down the common file from the parent to the child. Now, each child will have different content but the same common files. You can be very specific as to which file types to copy down and even use conditions to control the process.

The best part of this feature is that Flare maintains a link between a child project and the master. If one of the common files changes, because the child project author or the master project author changed them, the changed files are copied down from the master to the child projects, overwriting the previous versions in the child projects. In effect, you get invisible consistency – one of the most useful features in Flare.

3. Create Topic Type Templates

Consistent structures for similar topic types make it easy for authors to write and readers to understand the material. It’s easy to create topics to use as templates but also easy to accidentally overwrite them. Flare’s Template Manager feature lets you create Topic Type Templates, useful because they can’t be overwritten.

Adding them to Flare’s interface takes just a few seconds, and you can make them available over the network to all your Flare authors. For more information, see the “Managing Templates” topic in Flare’s help.

 4. Set Up Control File Folders

When you create control files like CSSs and master pages, Flare automatically puts some in sub-folders under the Resources folder on the Content Explorer and others, like table CSSs, under the Content folder on the Content Explorer.

Flare doesn’t care where these files are; it will find them wherever they’re located. You can also look for them in the list of files on the Content Explorer or by using the filters to list only the type of file you’re looking for in the File List, shown below.

Best Practices - File List Screen

However, anything you do to simplify your projects can only help. One surprisingly simple thing is to create sub-folders to contain the specific types of control files. While not a major workflow task, this is a great way to make it easier to navigate Flare and your projects.

5. Create a CSS

If you’re new to Flare, a CSS may seem like one more control file; it’s actually one of the most important. It lets you specify the formatting for a project and add features that support single sourcing and various types of file processing. Flare offers a very powerful CSS (stylesheet) feature that lets you customize the look and feel of your content.

Create the CSS early on in your project as a separate task, as it plays a major role in setting the direction of your content.

Proper Planning is Key

Proper planning is key when starting your first Flare project. But setting standards and controls that are common for multiple projects and authors can reduce project time and minimize confusion in future projects. By following the best practices above, you can start your Flare project without a hitch, and keep it under control.

For the full guide on best practices to starting a new MadCap Flare project, view the guide here. For any questions on getting started with your Flare projects, please feel free to add your comment on this post.

About The Author

Neil Perlin

About Neil Perlin

Neil Perlin is the president of Hyper/Word Services, an online content and app development firm based in Massachusetts. Neil is MadCap-certified in Flare and Mimic and a frequent speaker at MadWorld and other industry conferences. You can reach him at nperlin@nperlin.cnc.net, visit his web site at www.hyperword.com, or follow him on LinkedIn, Facebook, or Twitter (as NeilEric).

Last Modified: November 6, 2017

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

Comments

  • craig wright October 12, 2017 at 10:26 AM

    I’d add a couple of others –

    Try to plan your content reuse at an early stage, especially if there are multiple writers involved. It’s no good creating snippets if the other authors aren’t aware of them.

    Make sure your snippets are well organised. If authors struggle to find the snippets they need, they may create their own and duplicate existing content.

    • Neil Perlin Neil Perlin October 14, 2017 at 2:56 AM

      “Absolutely” to both of your points.

  • Stephanie M. October 12, 2017 at 1:39 PM

    Great tips! To go along with this, I would also recommend a file name convention. For example, my team names all files in lowercase and uses underscores instead of spaces. It is much easier to organize and find what you’re looking for.

    • Neil Perlin Neil Perlin October 14, 2017 at 2:59 AM

      As with Craig’s comment, “absolutely”. I include your points and Craig’s in the discussion when I’m on a consulting job; there just wasn’t room to include them in the blog post. But I’m considering writing a longer version of the blog post to put up on my web site. If I do, I’ll include both sets of points and mention you both by name as contributors.

    • Neil Perlin Neil Perlin October 14, 2017 at 3:10 AM

      I will add that the file naming conventions you list here are “programmatic” file naming conventions but not semantic file naming conventions. For the latter, you’d have to decide on rules for the actual naming of the files. That’s often the trickiest part.

  • colinwalters October 20, 2017 at 5:25 AM

    Great advice, I agree with every point. Another item to consider for multi-author and distributed projects is “core file discipline”. Designate one or two people as the owners and maintainers of important project files such as the CSS, page layouts, and build files. Establish a change control process for these core files so that content developers must request changes, and any changes are approved, implemented, and tested before the revised files are pushed to the live project. Some revision control systems might enable individual file locking to prevent core file changes, or you can put your core files in a separate project.

    • Neil Perlin Neil Perlin October 26, 2017 at 11:01 AM

      You guys are coming up with great comments. Absolutely agree.

  • Shelly C November 2, 2017 at 9:43 AM

    Thanks Neil, these are great tips! I manage a rather large project, so I started immediately organizing my snippets. To add to the naming convention points, I have created separate folders for my snippets: Definitions (def), Images (img), and Text (txt). Each type of snippet begins with that extension and then put into the correct folder (e.g., img-configuration_dialog). Even if you don’t think you’ll have lots of items, it’s best to start organizing from the beginning. It’s amazing the amount of information we have to keep organized and have access to.

Have Something to Say?

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