My Background
In the last job I held that required web output, I used Visual InterDev, as I was creating a program interface, not online help. Eons ago, I used RoboHelp and various other editors. I have been beta-testing MadCap Flare 9 as a TechWhirl assignment, but also with an eye for making a software tool choice for a company that has a huge quantity of complex legacy content. To that end, I tested Flare’s conversion capabilities with various documents, help systems, and books, which had been created over a long period of time in a variety of formats.
From time to time, I have edited web projects using tools like Notepad ++. Although I have tried out various XML editors, this beta trial of MadCap Flare was my first serious effort in a long time to use a tool to create online help. I do have a good semantic understanding of XML, HTML, CSS, and JavaScript, which came in very handy so that I could see what Flare was doing.
Flare’s wizard-based system is a joy to use. I am a longstanding command-line and text-editor devotee, but even I have to admit that a good GUI-based system is more effective and efficient in many circumstances. By using the appropriate wizard, you can create a new project, import a project, create or edit a stylesheet, export a project in one fell swoop, or other important tasks. Although I am sure there are ways to mess your project up, it is much harder to do so when choices are guided and constrained. One might say that Flare is “idiot-proof”, but I prefer to say that Flare helps protect a tech writer from the inevitable distractions faced during a typical day at the office.
General Editing in MadCap Flare 9
The whole point of an editor is to make it easy to do complex formatting. I enjoyed being how easy it was to add complex features like drop-down text. You can easily insert multimedia. You can preview the topic on the fly, and you can instantly switch between the text editor and the XML editor.
Like other complex software programs, it is easy to be overwhelmed by the sheer number of features available. Happily, with the View menu in Flare, you need only see and use those project components that are immediately relevant, and you can ignore the rest. Keep in mind that, some aspects, such as Link Viewer aren’t immediately intuitive. You need to drag a linked file to the View, but that doesn’t change the file contents.
Managing the Table of Contents
It is very straightforward to manipulate the topics and their positions. You can add or delete topics on the fly, and create new topics, and the same is true for books. In many cases, you will likely want to work directly from the TOC, as it provides a useful organizational guide.
Editing and Importing Stylesheets
Flare’s stylesheet editor is clear and organized, although I would prefer an option to append styles with new names rather than overwriting them when importing another stylesheet into an existing stylesheet, If you prefer to edit your stylesheet in a text editor, Flare provides that feature as well, and if you have Autocomplete turned on, that makes the text editor foolproof to use. Overall, the stylesheet editor provides a huge benefit, because it allows you to see all of a style’s attributes and then take advantage of the power of CSS.
Madcap Flare 9 Provides an Array of Conversion Wizards to Start a New Project
Generally Useful Features in MadCap Flare 9
I cannot say if these are unique to MadCap Flare, but I found these features very useful.
Clean Project
Have you ever gotten confused between previously generated output and what you hope is new output? If so, the Clean Project feature may come in very handy, as it deletes all previous output when you press the button.
Save Project as Template
If you have a project that you want to use as a basis for further projects, you can save it as a template. Then, when you start a new project with the New Project Wizard, you can select that template.
Zip Project
Do you want to send an entire project to a coworker or another computer? If so, just click Zip Project, and everything is done for you.
Snippets
A snippet is a block of text that you can insert into a topic and reuse across topics. You can create a snippet, which is saved in a file, and then insert the snippets as needed. If you edit a snippet, your help content that references the snippet will change as well. This is a great way to handle boilerplate text.
Variables are a similar concept, but used for words or short phrases.
Importing and Converting From Other Programs and Formats
Most technical writers have to deal with lots of legacy material, so it’s important to know how well your chosen tool can handle that. Any source material will have its own quirks, but here are some notes from my experiments.
DITA Imports
I experimented with the samples in the DITA Open Toolkit, and MadCap Flare successfully imports a DITA project. The New Project > DITA Document Set command opens a wizard that guides you through the import process.
Although Flare 9 will import DITA projects, it is still not a full-fledged DITA editor, which means that if you need full DITA support, you will have to rule out Flare. But you can still do organized, structured, topic-based authoring without DITA, and Flare 9 is a very useful tool for both the development and production of various forms of content.
The Challenges of FrameMaker and Word Imports
Although I was able to successfully import FrameMaker files when using a computer with FrameMaker installed, I was not able to import FrameMaker files when using Flare on a computer that did not have FrameMaker. I received an error message informing me of the requirement when I was working within a project, but did not receive an error message when importing a new project (the import simply failed).
When I tried to import a Microsoft Word document, I had a similar problem, but this time I was told to make a change on the Options menu. That was not easy to find (it’s a button on the File menu), but the option does allow you to import Word documents without having Word installed, warning you that the content may be affected.
I then threw an admittedly challenging document containing numerous styles and mathematical content at the New Project > MS Word Document Wizard. It complained about the inability to convert .wmf files, but finally produced a project. When I checked the File List containing the HTML files produced by this conversion, the documents had been broken out in a nonsensical fashion: some files had several copies, such as Absolute.htm, Absolute1.htm, Absolute2.htm, Absolute3.htm.
Most authors may not have this kind of challenging content, and so wouldn’t see this kind of result. For a simple Word document that did not have images or math content, the import was easy and successful.
MadCap Flare cannot magically create seamless document conversions when it comes to FrameMaker and Word. If your source document is well-structured, you will most likely have a smooth conversion. If not, the result will be disastrous—but the same is true of all the conversion tools that I have tried.
Web Help and CHM Conversions
I tried importing HTML files from the help system from an existing open source project at zyzzyva.net. Because these files were not properly formatted XML files, the import failed. On examination, these HTML files lacked HTML, HEAD, and BODY tags, which was not a problem for the original software program because it uses an open-source tool to create the help from this source. In general, the import works well. If your original files are not well-formatted, you may have problems on the import. “You can’t make a silk purse from a sow’s ear” applies to technical content too!
I chose a moderately complex CHM file that documents my Internet provider’s security advisor. Flare handled this conversion without difficulty, and it correctly noted an error in the CSS file. I tried generating HTML 5 output without any changes, and it produced high-quality output (without logos and other branding, as expected) immediately.
MadCap Flare 9 has an Equation Editor built in
Flare Equation Editor
I was particularly interested in trying Flare’s Equation Editor, updated for Flare 9, as I work with a great deal of mathematical content. Like other XML editors, Flare uses the MathFlow editor to produce behind-the-scenes MathML. The MathFlow editor is from Design Science, the company that produces MathType. Thus, if you are familiar with MathType, this editor is very similar. In any event, the editor is intuitive, and you can readily learn it. You can copy MathML from nearly any source into the editor, and MathFlow will display it. If you’re using LaTeX, it’s somewhat more complicated. If I could request one feature, it would be that MathFlow permits a direct paste of LaTeX markup into the editor. I found a workaround by using a LaTeX to MathML conversion first. In addition, Flare now supports the ePUB3 standard for ebooks, which greatly facilitates the production of ebooks with mathematical content.
Review Options
Flare has efficient options for sending topics out for review. You can create a package with the designated topics, and email them to a recipient. Note that you will need either to provide the mail server settings to Flare, or save the review package to a designated folder. Subscription packages include free licenses for MadCap Contributor, which allows folks who don’t have Flare to review and annotate content. With a full Contributor license, SMEs can edit content as well.
We round tripped a small file containing equations and Hebrew text and found that it worked extremely well. One thing we noted with the review packages: if you work with equations, and your SMEs will be editing content, they will need to install Ghostscript and the latest JRE to edit equations.
Translation and RTL Language Support in MadCap Flare 9
MadCap Flare 9 has right-to-left language support. I tested with some samples from right-to-left languages like Hebrew and Arabic as part of English-language files in an English-language help project, and Flare handled bidirectionality smoothly. Flare 9 has Language Skins for dozens of languages and various dialects that you can apply to your help projects. You can also define your own language skins.
MadCap Lingo provides powerful tools to manage translation and content management. I have not yet had an opportunity to test Lingo integration with MadCap Flare 9, but MadCap notes that it provides tight integration between Flare and all the products in the MadPak suite.
Interfacing with Programmers
Flare makes it easy to work with the programmers when you are creating context-sensitive help. Test CSH API Calls allows you to test context-sensitive help by topic ID. In addition, MadCap allows API access so you can make Flare extensible. If by some chance, there is a Flare feature you would really like to have, you can use this feature to create it.
You can choose between the XML Editor or the Text Editor in MadCap Flare 9
Overall Impression of MadCap Flare 9
My perception is that Oxygen may be a better choice for those who plan to be doing complex XML design and programming, or in need of full DITA support. But for the vast majority of technical writers, especially the ones faced with converting and managing legacy content, MadCap Flare 9 a great choice to manage help projects.
I will be using MadCap Flare 9 more in the future at my current job, and I am delighted that I was able to beta-test this program prior to using it in the office. I am impressed both by the array of features, and by Flare’s ease of use. Flare 9 is something of a behemoth, with functionality that I am unlikely to use, such as Source Control and Instant Messaging (my company has other tools in place for these), but are certainly helpful to other organizations with different requirements. Some features, such as managing print and web conditions within the same help system, are straightforward, and after a slight learning curve will provide huge benefits to me in my current role. MadCap Flare 9 is a versatile tool that answers a huge range of tech comm needs.
