One of the hardest things about entering the technical communication field is learning what authoring tools are being used and how to get trained on them. Authoring tools can quickly become a hot topic when you put technical communicators in a room together, as we all have our preferences. So if you’re new to the field or looking to change the authoring tools you use at work, read further for an overview of the different types, what they do, and examples to investigate.
Every few years, technical communicators are asked to fill out a survey indicating their current authoring and publishing tools. These surveys are enlightening in the trends they uncover. For example, from year-to-year we see that extensible markup language (XML)-based tools gain ground, but the “staples” remain Microsoft Word, Adobe FrameMaker, and Acrobat.
Many of the tools listed in these surveys can be broken down into five types. Purposefully left off are standalone Content Management Systems (CMSs) and Component Content Management Systems (CCMSs), as they are not authoring tools. Also not listed are ancillary tools like screen and video capture and editing, learning and training tools like Camtasia, Learning Management Systems (LMSs), presentation software, and website creation tools.
New content types—like video documentation—are being produced more often by more companies. Adoption of advanced information development management technologies like component content management systems (CCMS), XML authoring tools, and machine translation are planned innovations for firms hoping to lower costs and connect content to customers. —The Content Wrangler, The 2016 Technical Communication Benchmarking Survey
Desktop Publishing
Desktop publishing tools are standalone systems that live on your machine and allow you to author and publish from the same system. Content and format are integrated, the graphical user interface (GUI) of the tool is almost always What You See is What You Get (WYSIWYG), and the writer has control over how the content displays.
Generally files are stored locally or on a shared network drive, and it is rare to use a CMS or CCMS with these types of tools. Publishing is typically limited to PDF but other file types are possible, with additional add-ons or tie-ins with other systems. With desktop publishing, content is trapped in a document-centric container, which can be difficult for writers to move away from.
- Good for: Small teams, lone writers, non-profits, printed documentation, and content that is not reused or published to multiple outputs
- Examples: Google Docs, Microsoft Word, Adobe FrameMaker (unstructured), Adobe InDesign
Structured Authoring
There are many tools that allow you to reap the benefits of structured authoring. Some added benefits are collaboration, single-sourcing, topic-based authoring, translation management, and others. However, these types of tools are generally seen as “all-in-ones,” described in more detail below.
What we may call a structured authoring tool is essentially a text editor that you can use with a markup language such as XML or DITA to “tag” content based on a predefined structure or set of rules, called a document type definition (DTD). Structured authoring forces the divorce of content from its presentation, though some tools embed a publishing engine as a selling point.
- Good for: Medium-to-large teams, content that will be reused, translated, and/or published to multiple outputs
- Examples: Adobe FrameMaker (structured), oXygen, XMetaL, ArborText
Help Authoring Tools
Help Authoring Tools (HATs) are purpose-built for delivering browser-based help (Webhelp, also known as online help), or embedded/compiled help, such as CHM files (Microsoft Compiled HTML Help, or the results of pressing F1 in an application). Some HATs, like RoboHelp, can be considered a desktop publishing tool. This wouldn’t be incorrect, as authoring tools do have lots of crossover, but HATs have a specific purpose, so it’s useful to call them out separately.
Many tools have the ability to publish more than just Webhelp files; some can publish to PDF and to HTML5 for website creation. While you can create Webhelp from XML/DITA, these tools are designed to hide the markup code from the writer and provide a more WYSIWYG environment. Some HATs do not have an integrated CCMS to allow for version control and collaborative authoring, so that should be factor when considering switching to one of these tools.
- Good for: Small teams, lone writers, content that does not need to be translated and managed within the tool
- Examples: Madcap Flare, Adobe RoboHelp, Help & Manual, ClickHelp, Doc-to-Help
API & Developer Documentation
Documenting application programming interfaces (APIs) is a quickly growing niche within the technical communication field. Many companies are finding that technical writers are more equipped to document this kind of software better than the developers can. API documentation needs to be written, published, and hosted in a way that best fits the audience (usually developers or IT professionals), and there are many different solutions to fit this need, which is why it gets its own category.
API documentation ranges in complexity from a simple readme file to a standalone website aimed at external customers, such as Slack‘s. Often, this documentation is written in Markdown, a simple language that closely resembles wiki markup. This content lives in plain text so it can be integrated with the code and the source control mechanism. Content can also be generated from source code comments and published in an automated process.
- Good for: Writers in an engineering-centric group or software development company
- Examples: Sphinx, Swagger, Jekyll, Doxygen, Slate (and many others)
All-in-Ones
An all-in-one tool combines authoring, publishing, and content management into one tool. These tools typically use structured, topic-based authoring to publish to multiple outputs while also supporting reuse, translation, source control, and collaborative authoring. Market-leading all-in-one tools are rare because it is difficult to create one tool that does all of these things well. An all-in-one will probably get you most of what you need, but it may be necessary to purchase additional plugins, add-ons, or modifications to fully support your workflow.
- Good for: Large teams, medium teams without large budgets or technical resources, content that will be reused, translated, and/or published to multiple outputs
- Examples: Author-it, easyDITA, SDL Tridion Docs, IXIASOFT
If you’d like to learn more about how to determine the right authoring tool for your team or business, join me for my talk on November 29, 2018. Register today at the following link (it’s free)!