The need for robust tech comm authoring tools

by Tom Johnson on Apr 13, 2014
categories: technical-writing

Neal Kaplan recently posted about the search for a perfectly adequate authoring tool, which got me thinking about the tools I use.

At the time I joined my current company, I had to change my help authoring tools quite a bit. At my previous company, I used Mediawiki and Madcap Flare. Both tools worked pretty well. At my present company, we publish on Drupal, which is a web-based CMS similar to WordPress but more robust. All the content lives primarily on Drupal.

At first we authored directly in Drupal. However, authoring and managing tech comm content in Drupal isn't ideal at all. After a few weeks of working in Drupal, I adopted a combination of Markdown and Google Docs, which I wrote about here: A Simple process for authoring and publishing technical content.

However, while Markdown is a convenient way to produce HTML, it's not my favorite syntax. Some of the syntax relies on spaces (such as breaking a numbered list with 4 spaces to insert a note or codeblock). And there aren't any good tools for managing Markdown documents, nor are there opportunities for re-use, assembly into complex help systems, use of variables or conditional text, output to PDF books, and more.

I really miss the power and convenience of a robust tech comm authoring tool. The Markdown method was fine as an interim solution, but not long term. Markdown mostly addresses the needs of programmers who have simple documentation to write (like 5 pages, nothing more). At most, you might put your Markdown documents into a collection of articles, like you can with Nanoc.

One of the main problems with managing content in Drupal is that the content is hard to wrangle. I feel like there are endless pages (“nodes”) that just exist in the database. It's hard to read through the content and manage, shape, massage, and work on it as a whole. I know readers don't read the content as a whole, but it's important to make the individual pieces consistent with each other, especially when terms shift, features are deprecated, links once relevant no longer are, new functionality is added, strategies change, and so on. I need to regularly go through the documentation and make sure it's internally consistent, logical, clear, and accurate.

The problem with the online database model is that there are so many topics, it's hard to know where to begin or end. Sure, this may be the paradigm of the web – an endless collection of discrete topics, some relevant, some not, some updated, others not – all filtered by the user's search.

But that model paints a scenario that is more complex than it needs to be. My products aren't that complicated. They should be intelligible in a single read, more or less. I don't want to send the user in 15 different directions.

I would like to return to a time in which I could manage and shape the content in a robust help authoring tool. I've decided to try a new approach. I'd like to try the DITA option using Oxygen. (About 90% of the help authoring tools usually available to me aren't available because I'm on a Mac. Sure I could use boot camp to install Windows instead of Mac OS X, but doing that is too painful.)

One of my primary goals will be to single source both documentation and training from the same source, producing attractively designed training workbooks that rival the current styling and formatting (they're in InDesign). Figuring out how to customize and XSLT stylesheet in order to product output directly from Oxygen will be one of my first tasks. Getting the content into Drupal from the XHTML output will also be a challenge.