MadCap Flare is making headway as part of the technical documentation toolkit in New Zealand and overseas. In December 2012 and January 2013, I had substantial conversations with three different professional colleagues who were considering MadCap Flare. They had concerns about other single-sourcing products – too expensive, poor support, steep learning curves – and wanted advice from a MadCap user.

I’ve been working with MadCap software since 2009, when we moved our primary documentation maintenance from FrameMaker to MadCap Flare. It’s been a very positive experience, saving us time, almost eliminating buggy help builds and PDF problems, and making it easier to localize documentation. Along with the Flare documentation and ourput source, I’ve been using the Contributor and Analyzer modules, and our translators use the Lingo module.

I asked my colleagues why they were looking at MadCap for single-sourcing documentation. Challenges they shared included:

– Needing to convert a Microsoft Word or Framemaker documentation set for online help  and single-sourcing re-use
– Seeking a tool with a manageable learning curve and a manageable cost
– Often aware that single sourcing was supposed to be good, but weren’t sure of the benefits for them
– Team members had modest experience with single-sourcing content management systems

When we reviewed the Flare user interface, some common issues for new Flare users came up.

– “Looks awfully small.” Yes, it is. The screen layout is for someone with good eyesight, and the CSS format screens are particularly eye-straining. Also, the page view can’t be enlarged beyond 100%. This is a persistent usability issue – one that other single-source tools have, too.
– “When do I use snippets? Conditional text?” It’s easy for new users to get carried away using these convenient text functions. I also note that new users often create overly long topic files, using a “chapter” mindset.
– “How do we connect help topics to software pages?” Some users were disappointed to find out that this required collaborating with software developers.

Everyone was concerned about the process of converting MS Word or FrameMaker content into Flare projects, especially when I told them time frames for first-time conversions of large amounts of material. I encouraged everyone to convert intelligently – focusing on content required for the extended life of a product, that is to be managed long-term in MadCap.

When you’re converting  content into Flare, for a smooth conversion, format your documents meticulously. This includes:

– Avoiding MS Word or FrameMaker drawings – graphics should be embedded JPGs or PNGs. You can embed TIFFs and EPS graphics, but these can bloat your output size
– Making sure every single text instance has a clean format applied
– Reviewing your document’s headings and considering your content as potential Flare topics
– Removing heading numbering if desired (it’s much easier to remove this BEFORE conversion)
– You have to review everything after it’s converted to MadCap Flare anyway, so make good use of that review to avoid repeats

I also shared some overall MadCap guidelines:

– It’s good if at least one person on a MadCap project is confident with CSS,which is how MadCap applies print and online text formatting and layout. If you have a limited training budget, invest in CSS training for one or two people.
– Be meticulous about placing MadCap project internal files in sensible folders, with sensible file names. This is especially important for graphics files.
– To keep online help output lean, keep graphics small and make use of Analyzer’s reporting and Flare’s project generation functions. These allow you to remove unused graphics and block unused material from the final build.
– Don’t neglect the other MadCap software tools, Analyzer and Contributor. You’ll need to “sell” using the Contributor review tool to a software team, but it’s worth it.

One of MadCap’s benefits is its generally excellent support. (I noticed that their support went through an iffy stage for several months last year, apparently as new staff came onboard.) That said, I do recommend investing in Gold support, with phone calls, for at least one license – once in a blue moon, the immediate support makes the difference between making a deadline and not.

Another benefit, which gives MadCap strength as a long-term tool for a growing documentation set, is its localization support. I’ve managed localizations/translations for over ten years. And I enjoy Flare’s compatibility with the MadCap Lingo translation module. Potential MadCap users often quit listening to my praises of this halfway through, saying, “Oh, but we don’t need translation, we don’t need translation at all.” I’ve seen this change for so many companies throughout my career that I think all medium- to large-scale documentation sets should plan for it.

There’s much, much more to say about MadCap products. I’ve added some links with further discussion below. Ask any questions you like in the comments.

– Madcap Flare Review from I’d Rather Be Writing. See the related post What Tools do Technical Writers Use? which has comments about Flare’s current status among technical writers.
– Madcap Flare Review from PC World.
– Is it worth learning to use MadCap Flare? Discussion on LinkedIn.