Help authoring tools (HATs) and single-sourcing
- What are HATS and single-sourcing?
- Why I embraced HATs
- Why I abandoned HATs
- Current status of HATs
- Next post
What are HATS and single-sourcing?
Additionally, HATs solved a unique problem that was prominent during the early days of the web: how to generate both web and print content from the same source (single sourcing). PDFs are still in demand today (in my Dev Docs 2020 survey, 30% still produce PDFs), but wind back the clock 20 years and they were much more of a pressing deliverable to solve. HATs provided a unique solution for creating both the online help and printable PDF.
When I entered the field back in 2005, the industry standard HAT was RoboHelp. Later tools included MadCap Flare (spun off from the RoboHelp team), HelpNManual, Author-it, WebWorks, and more. HATs almost invariably worked only on a PC, and their tripane help output was clearly recognizable because the tools allowed for only minimal branding.
Why I embraced HATs
As a new tech writer, I joined a company that used a HAT (RoboHelp) as its standard tool. It did make authoring easy. RoboHelp was soon surpassed by MadCap Flare, which continued the same paradigm but improved it in many ways. When I switched companies, I was free to choose my own authoring tool and chose MadCap Flare. Two of my colleagues later went on to become Flare consultants and built up small freelance businesses around their Flare expertise (see Docguytraining.com and Smartoutput.com), the latter of which is still going strong today.
Why I abandoned HATs
The context in which I was writing documentation changed. I started working in an organization that had a strong community effort, with lots of volunteers eager to help out by writing content. Literally, I was working for the IT department of the Mormon Church, and we had hundreds of people eager to serve in whatever capacity they could. And guess what? Everyone can sort of write, right? :) Writing was seen as a near universal skill (in contrast to programming) where we could leverage volunteers’ contributions on projects.
To leverage these contributions, I needed a platform that would allow this wider community to create and share content in a scalable, free way. In short, I needed a wiki.
Current status of HATs
HATs are still popular, with more options that are cloud-based. MadCap Flare won the HAT battle, more or less. Flare is used by a huge number of technical writers who prefer to focus more on content than building out their own toolchain workflow and website framework. MadCap has expanded their toolset to include a suite of tools, not just a HAT. They have a popular conference every year (MadWorld) with a loyal, thriving user base.
Even so, HATs aren’t the primary tool choice for API documentation (see my Dev Doc Survey survey results on tools, which found about 8% use HATs), in part because of the lack of support for API reference documentation. And some are in fact using Flare for API documentation.
As long as PDFs are still in demand, there will be a need for HATs. Most tools geared towards creating websites (i.e., static site generators), don’t generate PDFs. There are very few tools that are designed to generate both web and PDF content (as well as other types). One nice thing about HATs is that they were created specifically for technical writers and usually accommodate every scenario you would encounter (content re-use, versioning, translation workflows, etc.).
The debate about single-sourcing continues today. In Heretto’s Content Components podcast, Patrick Bosek and Sarah O’Keefe engage in a fascinating argument about single-sourcing, specifically whether both instructional design/learning content and documentation content can be repurposed from the same source (See episode 38: The History of Content According to Sarah O’Keefe (Pt. 1)). They say some argue that learning formats work best in dynamic (“bouncy”) slides, while others argue that more plain-formatted content, which is accurate and reliable (being generated from the docs), does the job better. Either way, single-sourcing can refer to a number of topics, and is even something I touched upon in my tcworld China keynote.
HATs are relevant insofar as writers need to generate both web and PDF output from the same source. They also reduce the complexity of web publishing, but the closed source restricts their flexibility, and the licensing requirements limits their scalability in terms of authors.
Continue to the next post in this series: Wikis and crowdsourcing.
About Tom Johnson
I'm an API technical writer based in the Seattle area. On this blog, I write about topics related to technical writing and communication — such as software documentation, API documentation, AI, information architecture, content strategy, writing processes, plain language, tech comm careers, and more. Check out my API documentation course if you're looking for more info about documenting APIs. Or see my posts on AI and AI course section for more on the latest in AI and tech comm.
If you're a technical writer and want to keep on top of the latest trends in the tech comm, be sure to subscribe to email updates below. You can also learn more about me or contact me. Finally, note that the opinions I express on my blog are my own points of view, not that of my employer.