Why We Jumped From DITA and Doxygen to MadCap Flare

In my previous post, I mentioned that when I started at CM Labs, I recognized that we needed to switch from Oxygen XML Editor with Doxygen generation to MadCap Flare for our online help outputs. In that blog post, I outlined the steps we'd taken to update the documentation process, both in the tools we use and in the review process. This post will explain some of the reasons why the switch from DITA/Doxygen to MadCap Flare was necessary.

1. The Need to Streamline Authoring

It was clear that DITA XML was not ideal. I inherited DITA due to legacy reasons, from a time when our documentation was smaller and more technical, but it wasn't suited for the user guide we needed to publish.

Content reuse was difficult, and simply adding content was harder than it should have been. Instead of writing, I was spending much more time studying XML to avoid broken code that would ruin my doc builds. On top of that, the editing window was visually too busy, adding a layer of unnecessary obfuscation between me and the content I was trying to write.

Our documentation contains many chapters, topics and sub-topics that often change places, which is not the easiest thing to accomplish in Oxygen.

Having already used MadCap Flare in a previous job, I immediately recognized how simple it would be to perform all these tasks. New topics can easily be created and edited using the WYSIWYG editor, and reorganizing the table of contents is a breeze via dragging-and-dropping.

2. Building the Documentation

Perhaps the greatest reason that we switched to MadCap Flare was one of the most basic parts of the documentation process: building the doc.

When I started working at CM Labs, the documentation was written in DITA XML using the Oxygen XML Editor, and output into a CHM format using Doxygen. Doxygen is a powerful tool that can do a great many things, but getting to a point where one would be comfortable with its abilities is a painstaking process. I found pages of detailed instructions on the exact commands to run in order to build the help system. Stray from those commands and the tool wouldn't output correctly.

Worst still, these commands would call a script that would call another nested script that would call even more scripts, each intended to build the chapters separately, then put them together into one CHM package. On top of that, these impenetrable scripts would also run a converter that was built to generate Doxygen markup from the DITA XML source written in Oxygen. There were so many moving parts that even the slightest error at any stage could throw the entire output off.

And speaking of output, I desperately wanted to move away from the severely outdated CHM help format, a format that had not been updated by Microsoft in fifteen years by that point.

Time was also a factor. Due to the linked scripts and the nature of the form, each time I wanted to make a doc build, it would take a solid twenty minutes. Sometimes, I just wanted to see how a change would appear or test out whether a bit of XML code was working correctly, and each time I'd have to sink this time waiting for my output.

MadCap Flare solved these issues out of the box. Using targets, I could generate countless customized outputs in a fraction of the time at the click of a single button. Doc builds could be made via the command line, which is really helpful when integrating my documentation generation into automated scripts. As an added bonus, I could just press the little preview button baked right into Flare to see what a given page would look like without even having to make a full build.

Using Flare, I was also able to update the output to the modern and snazzy HTML5 output which is superior to CHM in virtually every way.

3. Importing the Source Files

Once we made the decision to switch from CHM (using the old methods) to HTML5 (using Flare), the question arose of how exactly would we bring over all the old content into this new software. Thankfully, Flare has a built-in CHM importing tool. All I had to do was point Flare to a CHM output and Flare did the rest. This one-time process looked at the CHM, took it apart, images and text alike, and reorganized the entire thing in Flare, copying the structure it found in the original help's table of contents. And just like that, I was ready to go in Flare, outputting HTML5 documentation shortly thereafter.

Parting Thoughts

Doxygen may have its uses but if you're in the same boat as I was in, MadCap Flare is definitely worth a look. It simplified every avenue of my work: adding new content, reorganizing topics, and building my online help. Flare has definitely enabled us to output modern-looking content quickly and efficiently, and without headaches.