The State of MadCap Flare in 2017 (published by an outsider)

I had a recent comment on a post I wrote nearly ten years ago. The post actually earned me a bit of notoriety in the MadCap community. For many years after writing that post, more about people would see me at an industry conference and say, prescription “Oh, you’re the guy who wrote The Six Things I Hate About Flare.” I would quickly correct them, telling them I was very careful at the time to not use the word hate. In fact, right after my actual post entitled “Six Persistent Flare Problems,” I quickly published a post on six things I loved about Flare. I published in that order, because I wanted people to remember the great things I said about Flare, not the quirks that annoyed me. (Nobody ever commented to me about the latter post though, so that didn’t really go as planned.)

A lot has changed in ten years! As I reread that post I realized that ten years ago, I was using Flare version 3. Since then, there have been annual numbered releases, all the way to Flare v12. Then MadCap changed the release naming scheme, and moved to a year-based name, so we got Flare 2016 r2, which could have technically been called Flare 13, but now MadCap posts the year of the release, and if a new major release is released in the same year, they add the “r2” addendum so you can see what version you’re dealing with. That means with Flare 2017, there have been 11 major release of Flare since my “persistent problems” post ten years ago. That is a lot of time, and A LOT of new features.

Now I am using Flare 2017. For your sake, I hope you are using Flare 2017 as well. I’ve been using it since it was released in January, and I’m exceptionally satisfied with the new features in this release.

In the past, I’ve talked in detail about the new features in a given Flare release. I think in this post, I want to take a slightly different direction and talk about my overall satisfaction with Flare as a technical writing tool, based on over a decade of experience working with Flare, training on Flare, and presenting on Flare to large audiences around the world.

Let me state my opinion right out of the gate: MadCap Flare is hands-down the best help authoring tool I have ever used. Its list of features is extensive, and the breadth and depth of its features is vast. The power of Flare is in its ability to help you reuse content in many different ways. You can write once, and maintain content in one single location, and then use that content in many different ways for many different audiences. Here is a partial list of single-sourcing features in Flare 2017:

  • Conditions – You can apply conditions to content, and then you can select a combination of include/exclude commands for conditions for each target that you build. (In the context of Flare, you can consider a target as a deliverable. It is a specific set of content published for a specific audience.)
  • Snippets – You can reuse chunks of content endless times across your project by putting shared content into snippets, and then referencing those snippets when you need them in other topics. When you need to make a change, you open the snippet, and the content is automatically updated everywhere you use the snippet.
  • Variables – Flare has support for several types of variables, allowing you to specify at the project level, or at the target level what the text of a specific variable should be. This makes it easy to create separate targets for specific customers where you can using the wording and terminology that is specific to that customer. Variables are also useful for items that may be used across the document, but may change over time, like the version number of the product you are documenting.
  • Snippet Conditions – An advanced feature in Flare, snippet conditions let you customize a snippet for use in multiple places in the project where the content is similar, but not exactly the same. You can then edit the conditions that are used for the snippet at either the topic level (all snippets in that topic will use the specified condition), or at the point the snippet is inserted (allowing you to use the same snippet in multiple places in the same topic, but with different conditions applied.
  • Snippet Variables – A fairly new feature, you can specify the variable text of a variable used in a snippet at the point of insertion, allowing you to set custom text at the point of insertion without having to specify the actual text in the variable definition, making it easier to use a snippet in multiple ways across the topic or project.
  • Multi-channel publishing – A Flare staple since the beginning, the number of ways you can publish content is increasing over time. Flare now supports  two flavors of HTML5 publishing, both a traditional tri-pane output and a new “Top-Nav” output that works more like a traditional website. Other targets include direct-to-PDF publishing, XHTML targets, DITA, Framemaker, and Word (to name the most popular).
  • TOC-embedding – In my experience, this is an oft-overlooked feature in Flare that allows you to single-source your TOCs and embed a TOC into another TOC. This means you can update the order of topics in multiple targets by editing the sequence in one TOC, and all other TOCS that use that edited TOC will automatically update. When you are working in small projects, this may not be too important, but for clients with larger projects (many I’ve worked with have dozens of TOCs; my main current project has 80 TOCs) this is a real life saver so that content in various TOCs don’t get out-of-sync with each other.
  • Project merging – In many writing shops, different groups of writers are working on different parts of a project, and at some shops, documentation may be created for separate projects that need to be merged into a single cohesive help system for customers. Flare allows you to merge project outputs, giving you that single system for customers.
  • Screen capture tool that uses conditions and variables from your project –  MadCap Flare ships a companion tool, MadCap Capture for free with each Flare license. Capture is a powerful tool that allows you to not only use conditions and variables in your screen shots (and they automatically get updated each time the project is built!), but it also keeps the content of the call-outs separate from the call-out itself, so you can edit call-outs, replace background images, and even translate call-out text easily at any point in the future.
  • Global project linking – If you need to work in separate Flare projects, but you have a core group of files you want to use in all your projects (style sheets, master pages, glossaries, corporate logos, etc.) you can maintain those items in a ‘master’ project, and then you can link your other projects to that master project and import those shared elements. Any updates to the master project will get pulled into the other projects before the other projects are built, so they always have the latest-and-greatest versions of those globally-used files.

And that is just a list of Flare’s single sourcing features!

What else do I love about Flare? Lets talk about the user interface experience. Flare is designed with the technical author in mind, and has many, many features that make creating and updating content easy and efficient. For example:

  • Customizeable user interface – Flare’s various windows and panels can be arranged in a virtually unlimited number of ways. If you have a wide-screen monitor or multiple monitors, you will especially appreciate Flare’s interface flexibility.
  • CSS-based styling – This is huge. Flare uses CSS for styling both online and print output. While you don’t need to know CSS to use Flare’s editors, the work in the background is being stored in CSS, and you can get in and manipulate it manually, so any CSS you learn (or already know) will help you style your content the way you want in Flare. Can’t figure it out? Look at the literally millions of websites and hundreds of books on CSS to find your answer.
  • Multiple editing views – One of the things I fell in love with in Dreamweaver many years ago was the split-screen view where I could see the code and the WYSIWYG editor at the same time. (This may be born of my love of ‘Reveal Codes’ from the old WordPerfect days.) Flare fully supports this. You can view just the WYSIWYG editor, or the text editor, or both at the same time. You can put the windows top/bottom or side-by-side. You can filter your current WYSIWYG editor by conditions, allowing you to see only specific conditions while editing. You can view your WYSIWYG window in print format (complete with pages based on existing page layouts in your system), or in web format (where you can even specify a specific media type). There are a lot of options, so you can work in the way that makes the most sense to you, based on the content you are currently working with.
  • Dynamic preview – This is a new feature in Flare 2017, and I love it already. I have an extra-wide monitor, and I love having the preview of my content being updated in real-time while I’m working.
  • Context-sensitive right-click – Depending on where you are, when you right-click in a topic you get a list of options. In a table, you get table-specific options. In regular text, you get different options. There are easy ways to insert links and cross references without necessarily looking at the entire list of your topics (a list showing, for example, all open topics, which can be quite useful in large projects).
  • Drag-and-drop – When you need to insert content from the Content Explorer into your topic, in most cases, you can just drag the item from the Content Explorer and drop it in your topic. This makes it super easy to add content to a topic.
  • Customizable keyboard shortcuts – Flare lets you create your own keyboard shortcuts for virtually every Flare function. I have keyboard shortcuts to apply specific styles, and others to run specific Flare macros.
  • Quick search – The main project I work on is big. Really big. Finding a specific topic can be difficult. I can use quick search to find any file in the project quickly and easily.
  • Quick-access toolbar – Like many Windows products, Flare lets me  customize the quick access toolbar at the top of my screen. I can even select sub-options (like a numbered list) and put them on the quick access toolbar making it very easy to find and use them.

And this is just a very short overview of what Flare can do. We haven’t even gotten into context-sensitive help, reports, the link viewer, group reviewing options, and integration with source control (including MadCap’s own Central offering). In my organization, we have our Flare project connected to GIT, which is connected to buildbot, so every time we check into GIT, buildbot generates a command-line compiled version of our targets, and copies the resulting files to an internal web server. Our developers and help authors always can view the most-recent content on the internal website, making it easy to review and approve topics.

In addition, I’ve had the privilege of being part of the Flare community forums for many years. That is a great group of people with a wide variety of experience and expertise who are willing to help users with questions that they have. The community forums, in addition to Flare’s excellent support staff, make Flare a very attractive tool because there are willing people who want to help you succeed in your project.

Are there things I’d like to see added to or improved in Flare? Sure there are. For example, I’d love to see Capture profiles stored in the Flare project, so they are available to all team members. I’d love to see more robust content management options for replacing live content on a schedule. I’d like to see a browser-based content review tool (taking MadCap Contributor to be a cloud offering) — something that might make MadCap Central a more attractive offering for a wider user base. I’m frustrated with side-menus in TopNav outputs not being location aware (if you have multiple topics used in the same TOC, only one of them is generated into the output, so the sidebar navigation is only correct for the first place the topic appeared in the TOC).  But these are all things I expect MadCap to continue to improve over time.

If we–from the outside–can judge based on the last ten years, it’s a pretty safe bet that there will be a lot of Flare goodness in store.

In the comments, tell me what features you think will be in Flare in the next ten years (Flare 2027(!), if the current naming scheme is continued).

, , , ,

11 Responses to The State of MadCap Flare in 2017 (published by an outsider)

  1. craig wright February 17, 2017 at 10:49 am #

    I agree with all the benefits and Flare is my favourite authoring tool too (though it is facing some competition now). But if there’s one thing that needs to change, and change quickly, it is the stability of the software. It isn’t as robust as it should be.

    • Jamey Parker February 22, 2017 at 9:01 am #

      I enjoy using Flare. I’ve used Adobe products, Microsoft, the old RoboHelp in its many variations – I find Flare to be as stated in this post, “features is extensive, and the breadth and depth of its features is vast.”

      However, I agree with Craig Wright. The stability of the software is an issue that seriously needs to be addressed.

      • Paul February 22, 2017 at 10:55 am #

        Hey Craig and Jamey, thanks for the comments.

        Please elaborate on your concerns with stability in Flare. Maybe it is because of my history with Flare, but I’ve found the later versions (maybe 9 and later) to be *much* improved in the stability department.

        I do see that Flare throws exceptions rather frequently, but now it allows us (in many cases) to report those directly to MadCap, and it doesn’t even crash Flare. You can just keep working. In the olden days of yore, Flare would just up and shut down with no notice, and no chance to save your work (like versions 2-6 or something).

        So, like I said, maybe it is my history with the tool, or maybe it is my configuration, but I don’t seem to have too many issues with overall stability of the product. Of course, YMMV, but I’d be interested in hearing more from you.

    • sanjsrik February 24, 2017 at 1:22 pm #

      Can you address what you mean by “competition”? I’m always interested in who is using something else.

  2. Mellissa Ruryk February 20, 2017 at 10:42 am #

    teeny weeny typo; Look at the literally millions ***on*** websites and hundreds of books on CSS

    • Paul February 22, 2017 at 10:50 am #

      Little mistakes like that drive me crazy! Thanks for catching that! I’ve fixed it, thanks to you.

  3. sanjsrik February 24, 2017 at 1:28 pm #

    can you also talk about what you DON’T like in the current iteration that should be improved? I can think of a few things off the top of my head:

    * better git integration (if they could fix this that would solve A LOT of issues)
    * speed and crashing issues (opening and navigating around a git-bound projects takes upwards of 5 minutes sometimes to switch between project and content explorer)
    * clearer online help (the current online help is not very clear to use for certain topics such as mini-tocs and so on)
    * Confluence support (this would be huge if I could publish TO Confluence, although I suspect that this is more of an Atlassian issue than anything else)
    * This isn’t related to the application but to MadCap, more transparency around bugs and enhancements submitted through various channels and what the status is around when/if/ever they will be released. Digging out the release notes on any given release is an act of will because they bury them in the knowledgebase while putting out marketingy types non-informative “release notes” which honestly, if you’re going to get marketing to write them, get the devs to include the issue number and a link to what was fixed and a clearer explanation in the KB (real) release notes

    • Paul February 25, 2017 at 1:54 pm #

      Hi sanjsrik, and thanks for your insight.

      Near the end of my post, I did mention several things that I thought could be improved. One thing is that I wish it were easier to get reviews on documentation. I’d love to see some kind of review feature built into MadCap’s Central offering, because I think there could be real power in gathering review data in the cloud, inserting that into the project and letting help authors see that as incoming reviews when they are authoring in Flare. In my opinion, that would make Central a much more interesting offering.

      In addition, source control (as you mention) is an area where I think there could be some significant improvement. Specifically, I’d like to see the ability to branch and tag and switch branches in Flare. To do any of this release management you currently have to have a third-party tool. For projects bound by SVN I use TortoiseSVN. For projects bound by GIT, I use SmartGit, but it would be very nice to be able to do that kind of work in Flare itself.

      I am sorry that you (and others) have had stability issues with Flare. My main machine is a developer-level machine with a 1TB SSD hard drive, 32GB of RAM, and a quad-core i7 6800 processor. With that configuration neither I nor my colleagues (who have the same model of computer) experience much product instability. Thus, it is hard for me to comment much on stability issues. This leads me to wonder if those of you who are experiencing stability issues might have better luck with a more powerful machine. In fairness, I will say that my GIT-bound projects are not connected to Flare. In fact, I told Flare to not recognize GIT bound projects at all (File > Options > Source Control > Bound Detection). I do all my source control management in SmartGIT.

      I will be honest and say that I don’t have a lot of experience using the help system. I’ve been using Flare for more than a decade so I don’t spend much time in the help system. I have heard people who feel both like you, that it can be improved, as well as people who think the product help is pretty good. I would say that when you find a topic that doesn’t meet your quality expectation, you should submit it as a bug to MadCap. Their writing team are good people, and I’m confident they would welcome constructive suggestions for improvement (as we all would as writers, right?).

      As for Confluence, it isn’t a tool I’ve used, so I don’t have a strong opinion on the topic. I have heard people in the past requesting an integration with database-based tools like ServiceNow or even WordPress. That is inherently difficult because of the way Flare stores files (flat file system with raw XML pages), vs a database storage system where a primary key is the unique identifier of content. Merging those is problematic. A one-time publish out to a DB isn’t as difficult as maintaining it would be. The other problem with collaborative editing tools (like I assume Confluence is) is that when you are using a help authoring tool like Flare, the source content in Flare is the authoritative source. You always republish from the Flare project because that is where the most current and correct information is. If you are using Confluence, and somebody edits the document, Flare has no way of knowing that the content was changed. So Flare loses it’s value as the authoritative source, and you can’t publish from Flare because you are worried about overwriting somebody else’s correct edits that were made elsewhere. I think Flare’s term, “publishing,” is a pretty accurate term. It is a one-way passing of information from the authoritative source into a variety of different targets for consumption only. It would be a dramatic perspective shift if you were to somehow try to make that publishing process a two-way process where edits made in the output had to make their way back into Flare somehow. (Which seems possible to me only if Flare really controls the target; so in Central, MadCap could do this with relative ease. But trying to do that with content stored in a relational database like WordPress or a wiki, or ServiceNow? That is very complicated.)

      I agree with you that feature requests often seem to go into a black hole. However, I have had many times in the past where Flare releases an update, and then I get an email saying that a feature I requested or a bug I submitted had been resolved by the latest version of Flare. In addition, I don’t know of any company that has great transparency on feature request progress. Some of this is for legal reasons (public companies not being able to speak about upcoming releases), others for practical reasons. I don’t see MadCap as being unusually difficult in this regard. I think it is pretty normal for a software company that is not open source.

      Anyway, thanks again for your comments!

  4. sabine March 2, 2017 at 6:50 am #

    Thanks for this great article and experience sharing.

    I’m about to use Flare along with Git and was wondering about a feature you highlighted: Global project linking.
    From my Flare trial period, I was not successful at having 2 Flare projects hosted on a Git repo.
    **** Is it really possible to use the “Global project linking” together with Git, and if yes, could you tell more about the way to achieve this?

    It seems to be THE feature I’m looking for but do not manage to set it up. Idea is to have a master project that manages the stylesheets and common reusable elements, and then 2 children projects for 2 different products and their proper content; all of those stored on Git…

    • Paul March 3, 2017 at 12:26 pm #

      Hi Sabine, thanks for your comment.

      A discussion on global project linking does not necessarily have to even involve a discussion of source control, since they can be totally independent.

      Let me present two scenarios that I this will illustrate this better.

      In the first scenario, you store your global project (I’ll call it the ‘parent’ project) on a location where you can access it on your computer. This may be a local drive folder, or this may be a network share. If everybody who needs access to the project can access it in that location, then you don’t need to worry about source control. In this scenario, we’ll assume a group of three writers, all of which have access to the same project on a network share. We’ll also assume that these three writers have mapped the network share to the same drive letter.

      These users will have the child project on their owner computers (and will be connected to source control as well, but the provider is irrelevant to this scenario). In their child project, the will use the Import > Flare Project feature to link to the parent project and pull down whatever changes have been made to the parent project.

      Note that while the child projects reside on each user’s computer, the parent project only resides on the network share. Any changes are made to that project on the network share, and Flare will automatically download the linked files into the project.

      Now what is cool about this is that since the files are all connected to the same drive letter on the network share, and since the Flare Project import file is stored in the Project Organizer, ANY USER ON THE TEAM can run the build, and the import will happen as part of each build process.

      Okay. Let’s talk about the other scenario. You store your parent project in source control and all three writers have access to that repo. Each member of the team regularly pulls down the updates from the repo onto their machine. Additionally, each member of the team has a copy of the client project on their machine, and they are downloading and uploading changes related to the project through source control.

      You will still use the Import > Flare Project feature, and that file will stay in the project organizer, but you need to make sure that every writer is storing the parent project in the exact same location on their hard drives, because the import file will be referencing the absolute path.

      That means, I can’t store my copy of the parent project in a folder like c:\Users\Paul\Documents\MyProjects\ChildProjects

      If I DO store my parent project there, when my colleague Claire tries to use the import file in the project organizer, Flare won’t be able to find the project, and it makes sense: Claire doesn’t have the c:\Users\Paul folder on her computer.

      So, in this scenario, you need to store your parent project someplace like c:\ParentProject, and you need to make sure all writers on your team use that same location. That will make it so the import file works correctly for all users.

      Finally, in the second scenario, you need to remember to go pull the uploaded files from the parent project before you build the child project. When the import runs in the child project, it doesn’t check the parent project’s source control for updates. (Well, I don’t THINK it does. If it does, that would be really cool, but I don’t think it does that.) So you need to do that manually. (Note: Flare WILL check the child project’s source control link for changes, but that is because Flare has the project open and can see the binding to source control. When it imports, I don’t think it sees the binding; it just imports the flat files without ever actually opening the project.)

      So, that is a really long answer to your question, but I hope it helps. Let me know if (where?) you need clarification!

Leave a Reply