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.
A good post. There is today an overabundance of hand-built authoring and delivery work flows based on “free” open-source software. The first problem with that is that the costs of setting up and maintaining those work flows quickly overtakes the costs of most “expensive” authoring and delivery products.
The second problem, one generally overlooked, is that of training a new hire (or worse yet a temporary contractor) to use the one-off work flow. It’s much easier to find someone who has experience using a particular authoring and delivery product and so can become productive almost immediately. Complex hand-built work flows require much more training and hand-holding before someone can begin to use them productively.
Yes, exactly!
Vrej, thanks for your post!
From I could understand, your old workflow was to edit DITA documents in Oxygen XML and feed them to Doxygen to generate the output, right? Did Doxygen did parse the code as well?
I’m asking because we’re thinking about adopting Flare as our documentation tool, but we’re unsure on how to use it to document code.
I was thinking about a workflow that would be the opposite to what you did: use Doxygen to parse the code, and then import content XML + Doxygen’s XML output into Flare to generate the output.
Now with Flare, are you parsing code at all, or just ” manually” documenting it?
Hi! Thanks for the comment.
To be honest, we’re still running doxygen to generate a set of documentation exclusively for documenting code (functions, classes, etc.). It doesn’t look pretty but it’s the fastest way to canvas the code, pull out the headers and compile something.
The problem was we were also using DITA/doxygen to do user documentation, which I had issues with. Hence, switching to Flare and bring all the user doc content along.
Sometimes, I do document bits of code in Flare, and for that I use Prettify to format the code snippets. Prettify is a free javascript tool that plays nice with Flare, used to, well, make code look more pretty in your HTML output. It works well.
Thanks so much for your answer, it was super helpful!