22 September 2011

It’s just HTML

This blog post is based on a lightning talk I gave at the Technical Communication UK conference in Oxford on 22nd September 2011. The theme was ‘If I ruled the world‘, and the topic was ‘authoring tools that limit the way we work‘.

Before I start, I should note that I’m going to be talking about Author-It here, but this isn’t a rant about Author-It. Instead it’s an argument that we don’t actually need anyone’s help authoring tool at all. Also, I’m assuming that you’re outputting your content primarily to the web; if you’re not, you should already be asking why not, but that’s a whole different discussion.

Recent development work on the ANTS Memory and Performance Profiler has required me to do a few things that push the boundaries of the tools and infrastructure that we use at Red Gate. For example:

  • The Memory Profiler has the new Instance Categorizer graph, which cannot be described without a screenshot wider than the 630 pixel width currently allowed by our website.
    The solution I adopted was to use jQuery to zoom into the screenshot when the mouse is hovered over it.
  • The Performance Profiler has a new demonstration application, which (although very straightforward) takes 41 steps to describe.
    If the description were in simple text form, it would doubtless be off-putting to evaluators. By splitting it into a Flash presentation, with lots of screenshots, the demonstration hopefully doesn’t seem to be so much of a chore.

Both of these should be possible in Author-It, our current Help Authoring Tool (HAT), using HTML Snippets. Snippets aren’t a great solution though because they require working with raw HTML which doesn’t always display in the editor. It’s even more of a problem for us, because the XSL transforms applied during our publishing process tend to break unusual things in the Author-It output anyway.

As a result, I started intervening in our publishing system, by manually editing the HTML output between the output of the XSL and putting the page on the website.

Given the numerous problems we have encountered using Author-It (those of you who have followed my colleague Roger Hart @RMH40 on Twitter for a while will already know about these difficulties, so I won’t repeat them here), I started to wonder what benefits we gain from it.

Let’s take a look at the main features Author-It provides according to its own website and consider how you could replicate these features on the web without the tool:

  • Reuse existing content as you type, prompting you with similar or identical phrases used elsewhere in the library.
    Server-side includes are easy in most publishing systems on the web.
  • Work in an optional web-based authoring interface, allowing staff anywhere with an internet connection to log in and work.
    Wikis (for example, MediaWiki, Atlassian Confluence and even SharePoint) do that… though I’m definitely not suggesting using SharePoint for documentation.
  • Manage workflow to assign content tasks, track the results, and view overdue tasks
    If documentation tasks are in the company’s existing bug tracking system (at Red Gate we use Atlassian’s JIRA), you don’t need another tool to manage workflow.
  • Review and edit content in real time
    What does this even mean? That you type a letter on the keyboard and it appears on the screen immediately? Well yes, even Notepad does that.
  • Localize content as it’s ready, reducing localization costs
    We don’t localize our products, so this is perhaps a more major consideration for other organizations, but surely web pages could be localized when they are ready too?

Given the lack of a compelling argument in favor of Author-It here, I asked on Twitter what features users most value in a HAT. The answers were:

  • User-defined variables
    Again, this is trivial in most scripting languages for the web.
  • Style control for online and print
    The @media type in CSS2 allows you to specify different online and print formats.
  • Code editing
    Most HTML editors allow you to edit the HTML code manually.
  • Single-sourcing
    I’ve always been fascinated by the industry’s fascination for single-sourcing. I’ve never found it useful personally. But anyway, as noted above, single-sourcing is basically a server-side include as far as any web developer is concerned.
  • Link viewer
    This is the ability to see which pages link to which other ones in your content and, OK, I’ll admit that I’m a bit stumped on this one. After publication, Google Advanced Search can do this but to do it before publication you’d need to write a short script to crawl your content on a test server. It shouldn’t be too hard, however.

So, there’s possibly one feature for which a HAT is actually useful.

Actually, from my own experience, I can add another two: creating Tables of Content, and the ability to quickly compile the HTML output to CHM or PDF. Neither of these is insurmountable, though.

In conclusion, my thesis is that, if you’re outputting primarily to the web, a HAT is basically an impediment to your ability to innovate. Let’s just not use them, and replace them with a sensible HTML editor, such as Adobe Dreamweaver. That will allow us to do anything that the web has to offer.

It also opens to door to using proper content management systems, improved meta-data and, for us Author-It users who are reliant on that product’s limited implementation of source control, access to proper version management.

Ultimately, all we’re doing is putting HTML on the web; and editing and publishing web pages has been a solved problem for well over a decade. This approach allows us to concentrate on the writing (which is our specialism), and not to worry about the tools we use.

Although this lightning talk was well received at the conference, I suspect it might get a lot more comment published on the web. Please do give me your feedback. Is there something I’ve completely missed?

For more articles like this, sign up to the fortnightly Simple-Talk newsletter.


  • Rate
    [Total: 0    Average: 0/5]