The Joomla! Community Magazine™

Using Joomla! as a Help Development Tool

Written by | Wednesday, 01 January 2014 00:00 | Published in 2014 January
In my first article, I posed the idea that Joomla! could be the next "killer app" for professional writers. In this article, I compare Joomla to commercial help development tools and, hopefully, provide writers with a compelling case for switching to Joomla. I think Joomla offers the best path forward in the evolution of help development.
Using Joomla! as a Help Development Tool image by @Helvecio

Working with commercial help development tools

The help development tools we use to create help systems have not changed much in the last 10 years. With them, we can either produce compiled help files, or "web-help" systems, which are collections of HTML files and JavaScript that display or run within the frames of a master HTML file. We can spice-up our help topics with dynamic hyperlinks, like popups, via canned JavaScript libraries. In addition, we can add graphics and sometimes video, create glossaries, and tag help text for indexing.

When documenting a commercial software application prior to Joomla, I used a help development tool and delivered the help system to the software development team near the end of the development cycle. I usually provided compiled help for a thick-client application, which the developers bundled with the application in an installer. And, I delivered web-help for a hosted, web-based application, which the developers dropped into a folder on a web server.

This process worked well for many years. However, while a pretty good system, it still had a few drawbacks. For example, I had to work within the timeframes of the development cycles. While code freeze is a great idea in theory, I have only worked on a few mature projects where features weren't crammed into a product at the last minute. This often meant I worked many hours at the end of most development cycles to deliver the help on time (with the rare occurrence of new features getting delivered in the final build that went undocumented).

Another drawback was the discovery of typos or inaccuracies in the help after the final software build, which I couldn't correct until the next release. Sometimes, errors had to remain uncorrected for long periods of time.

The size of compiled help files for feature-rich applications also caused problems. In cases where we pushed applications to customers from a website, we had to ensure the installation executables were as small as possible, because we had to account for a variety of connection speeds (many customers had very slow connections). There were a few times when the developers and I wrestled over the size of a compiled help file and, in the end, I had to remove "extras" like graphics to reduce the help file size. So, the installer was smaller, but the help was less-usable.

Last, but not least, commercial help development tools are expensive. There are only two players in the market and, with so little competition, there are no real pricing battles. Both companies sell their products at around $1,000. But, worse than that, one of them is adopting a licensing model. When your license expires, you have to purchase another one, or your software stops working.

Working with Joomla

Now that I use Joomla as a help authoring tool, I can provide readers with the same or, in most cases, far-better functionality than I could provide in a static help system. For instance, I can add popups, graphics and video to my articles, as well as create glossaries, and tag articles, most of which I could do with static help systems. But, where I could only add text-based popups with a help authoring tool, I can add popups containing text, images, video, and other types of media using the JCE MediaBox plugin for Joomla. I can perform other tasks with Joomla's core features that aren't possible with static help systems, like deploying surveys at any time for any article, and reviewing article usage statistics.

I no longer have to work within the constraints of software development cycles because my help sites aren't bundled with the software. The only connection between an application and one of my Joomla help sites is the Help button, which links to the appropriate URL. When developers add features to a product either at the last minute or in the final build, I can keep working until the end of the overall project schedule. In fact, I can continue documenting features after a product has been released (which, while possible, isn't the ideal process).

When I, or others, encounter procedural inaccuracies or typos in a help system, I can correct them immediately. I don't have to wait for the next software release to make corrections.

My Joomla help sites run on their own servers and I am no longer limited by size restrictions. I can add graphics and a variety of media to my help articles without affecting the size of our applications.

Best of all, Joomla is free, open-source software, and I can install and upgrade as many instances as required without spending a dime. The only way I would return to a commercial help development tool would be if I changed jobs and couldn't sell my new employer on the idea of using Joomla – but, you can be assured I would give it a try.

Author's note: This article is longer than I originally planned. I was also hoping to include a description of how I create and deploy Joomla help sites in a corporate environment. I will try to cover how I use Joomla as a help platform in a future article. Your comments on these ideas are welcome.

Read 8936 times
Tagged under Sitebuilders, English