Choosing a doc toolkit
I have spent the last year at my current job working on transitioning our docs from Madcap Flare to Antora.
First things, Madcap Flare is a great tool. This is the third place I have worked that has used Flare for some form of documentation, and it does its job well. However, there are several factors that impacted the decision to move away from Flare to another tool.
- Flare is proprietary software that requires a not-insubstantial subscription license to use. The cost of ongoing licensing, while not a deciding factor in the decision, was a factor.
- Flare requires Microsoft Windows. While it runs well in a virtual machine, and many people use Flare on Macs quite successfully, the fact is that a legitimate copy of Windows is required, raising the cost yet again.
- For our HTML5 doc site, Flare offers three choices for search mechanisms. For one or another reason, none of the options really met the needs of our users. The biggest factor in any tool we chose would be the ability to provide a better search experience.
- I am the only technical writer at my company, and I sit on the development team. Flare, as great of a tool as it is, has a steep learning curve to use. In the event that I am ever proverbially “hit by a bus,” I want to make sure that one of my teammates can step in, edit docs as necessary, and build them. Antora is a static site generator that sits within the docs-as-code space. I feel confident that any developer on my team can read the Readme I drafted and make necessary modifications.
What’s the takeaway?
There are many, many, many good options for choosing how to write and deliver docs. A good tech writer can take the tool they have and make great docs out of whatever they are.
But the best tool for a job is specific to the situation and people that surround that tech writer.
But the best tool for a job is specific to the situation and people that surround that tech writer. If in the future I find myself sitting on a team of tech writers, I would definitely consider a tool like Madcap Flare again. If I created docs that needed multiple types of output, Madcap Flare would once again be a solid choice.
But for my specific situation, a docs-as-code approach with a tool like Antora backed by a markup language like Asciidoc is going to serve us very well.
In another post, I will describe what drew me to Antora specifically out of the many other options that are out there.
