This guest blog post was written by Vrej Hezaran, a computer engineer (B.Eng.’04, McGill University) with over a decade of experience in technical writing. After school, he started out as a programmer in the mobile games industry before gravitating towards the intersection of language arts and technology.
In my previous post, I mentioned that when I started at my previous job, I recognized that we needed to switch from Oxygen XML Editor/DITA with Doxygen generation to MadCap Flare’s advanced authoring and publishing system for our online Help content. I outlined the steps we had taken to update the documentation process, both in the tools we use and in the review process.
This post explains some of the reasons why the switch from DITA/Doxygen to MadCap Flare was absolutely necessary in my mind and provides an excellent, cost-efficient DITA alternative to use.
1. The Need to Streamline Authoring
In my previous post, it was clear that DITA XML was not ideal. I inherited DITA due to legacy reasons, from a time when our technical documentation was smaller, but it wasn’t suited for the user guide we needed to publish. That documentation started out being more API- based, so when it came time to create a user guide (UG), the UG sprang out as an offshoot using the tools to which they were already accustomed.
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 contained 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 previous jobs for its structured authoring, I immediately recognized how simple it would be to perform all these tasks. New topics can easily be created and edited using the visual XML editor, and reorganizing the table of contents (ToC) is a breeze via dragging-and-dropping topics.
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 with structured content.
When I started working at my previous company, technical 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 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 but a little, and the tool wouldn’t output correctly.
On top of that, 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. And then, 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 for a technical writer to consider 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 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. That’s a lot of coffee breaks for just trying to create a document!
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 as a technical writer, 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 we would 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 ToC. And just like that, I was ready to go in Flare, outputting HTML5 documentation shortly thereafter.
More recently, Flare added a feature to bring in Markdown content as well, which only further enriches its import suite. Each such addition makes the jump from other content to Flare that much easier.
4. Content Reuse
As I briefly mentioned earlier, content reuse was pretty difficult in the old way we used to do things at my old job. As technical writers, we know just how important it is to have a single page and include it among different ToCs. Single-sourcing like this is at the heart of technical writing efficiency; instead of maintaining multiple copies of the same content (risking some copies not getting updated), you can use a single file across multiple outputs. A change in the one place ripples out everywhere.
Flare by no means has a monopoly on single-sourcing content but what it does do is make the process very simple. The WYSIWYG editor makes it clear what source files you have in your Content Explorer. If you want that file to appear across multiple ToCs, you just drag and drop it to the appropriate spot. If that information has to exist in multiple places in the same ToC, you just drag it into the right spots.
Then there’s content reuse in smaller formats with the use of snippets and micro content. Instead of writing out the same information over and over, snippets allow you to create a reusable chunk of text as a separate file, dropping the snippet into a page wherever it’s needed. Altering the snippets updates the info everywhere you placed it. On the other hand, micro content lets you create short, concise information that can be easily digested, perhaps as a featured question and answer in search results.
The ease with which Flare allows the user to create reusable content like this elevates the documentation experience for the writer, which ultimately benefits the reader, as well. And isn’t that the goal?
Doxygen may have its uses but if you’re in the same boat as I was, MadCap Flare is definitely worth a look. It simplified every avenue of my work: adding new information, reorganizing topics, building my online Help, and reusing content. Flare definitely enables its users to create and publish modern-looking content quickly and efficiently, and without headaches.