In contrast to docs-as-code tools, help authoring tools (HATs) refer to the common toolset often used by technical writers. Common HATs include MadCap Flare, Adobe Robohelp, Author-it, and more. You can use these tools to create API documentation. There are pros and cons with HATs.
Here’s a sample help output from Flare for the Photobucket API:
Some advantages of using a HAT include the following:
If writers are going to be creating and publishing the documentation, using a tool technical writers are familiar with is a good idea.
When you have to deal with versioning, translation, content re-use, conditional filtering, authoring workflows, and PDF output, you’re going to struggle to make this work with the other tools mentioned in this course.
You won’t have a division between an output that is generated from a reference doc generator (such as Swagger) and user guide material. It can be one seamless whole.
HATs reinforce the fact that good API documentation is more than just a set of endpoints and parameters. Good API documentation includes guides and tutorial topics as well. Developers rarely write that kind of information, yet it’s just as important as the reference documentation. HATs lend themselves more to these guide and tutorial topics.
Some disadvantages of using a HAT include the following:
Almost no HAT runs on a Mac. But many developers and designers prefer Macs because they have a much better development platform (the command line is much friendlier and functional, for example). To make a cURL call, you just open Terminal and paste in the call. With a Windows machine, installing cURL and libcurl is much more onerous and harder to use.
If most developers use Macs but you use a PC (to accommodate your HAT), you may struggle to install developer tools or to follow internal tutorials to get set up and test out content.
The output from a help authoring tool usually looks dated. The problem with the dated tripane look and feel is that API documentation is the interface that users navigate. There isn’t a separate GUI interface that the help complements. The help is front and center as the information product that users get.
If you want to promote the idea that your API is modern and awesome, you want a website that looks modern and awesome as well. In fact, you might have a UX developer create the website itself. If you lead with an outdated tripane site that loads frames, developers may not be as excited to use your API.
In Flare’s latest release, you can customize the display in pretty significant ways, so maybe it will help end the dated tripane output look and feel.
Many of the API doc sites are single-website experiences. The API docs are usually part of the main website, not a link that opens in its own window and frame, separate from the other content.
If you can output a format that another site can consume, great. But if you split and divide the user into separate sites, you’re following a less common pattern with API doc sites.
If you’re hoping for developers to contribute to the documentation, it’s going to be hard to get buy-in if you’re using a HAT. HATs are tools for writers, not developers. (Then again, if you don’t expect developers to contribute, then this becomes a moot point.)
If you would like to contribute back and encourage more available content and resources, you can click the Donate button below and contribute any amount.
Get new posts delivered straight to your inbox.
© 2017, Tom Johnson