Linux Technical Writing Tools
By Scott Nesbitt

One of the necessary evils of software development is documentation. This can include printed and electronic manuals, online help, and documentation for programmers. In the Windows world, technical writers rely on applications like FrameMaker, RoboHelp, WebWorks Publisher and, in some cases, Microsoft Word, to author documentation. These tools, while considered the standard for creating documentation, aren’t available for Linux. But that doesn’t mean Linux isn’t a viable environment for technical writers.

While there is a dearth of graphical Linux documentation tools, technical writers have a wide range of other documentation software at their disposal. The right hands can use that software to create high-quality documentation.

DocBook XML

DocBook XML (http://docbook.sourceforge.net) is arguably the biggest gun in the Linux technical writing arsenal. It’s a variant of XML that has been designed specifically for authoring software and hardware manuals. DocBook XML consists of more than 400 tags, which do everything from defining the structure of a document to creating tables and lists to add formatting to individual words and phrases.

One of DocBook’s strengths is that it can output documentation in multiple formats, including PDF and PostScript (for printing), HTML, and HTML Help and JavaHelp (for online help). On top of that, DocBook XML supports profiling. Profiling comes in handy when you have two or more documents that contain much of the same content, but which are intended, for example, for different users or different operating systems. So, if you need to create user guides for Linux and the Mac OS, you can profile your document so that your XML processor generates the appropriate version for the appropriate operating system. This enables you to maintain all of your information in one file rather than having to maintain multiple documents.

You produce output by applying XSL style sheets to documentation using an XSL processor. The style sheet determines the output format, and the XSL processor does the grunt work. For most formats, you use an XSL processor like the popular Saxon (http://saxon.sourceforge.net). To create PDF files, you first run your document through an XSL processor and then through an XSL-FO processor like FOP (http://xml.apache.org/fop). The XSL-FO processor takes the transformed DocBook file and converts it to PDF.

Online Help

Not everyone wants to read or even thumb through a manual. They want to press <F1> and get help. There are several strong tools in Linux that technical writers can use to create online help.

A popular tool is QuickHelp (www.excelsoftware.com/quickhelplinux.html). QuickHelp is a graphical help-authoring tool that enables technical writers to easily write and format help topics. It can also compile the topics into a professional-looking help system that includes navigation, an index, and even a simple search engine. The drawback, for some, is that you have to pay for QuickHelp.

JavaHelp (http://java.sun.com/products/javahelp) is designed to deliver online help for software written using the Java programming language. It’s a powerful and flexible system, and Linux has several authoring tools available for creating JavaHelp systems. Two of these are JHelpDev (http://jhelpdev.sourceforge.net) and JHelp Builder (www.javio.com/jhelpbuilder), which provide a graphical environment in which you can create help topics and all the supporting files needed by a JavaHelp system. DocBook XML can also output JavaHelp.

HelpSetMaker (www.cantamen.de/helpsetmaker.php?lang=en) is a free graphical help-authoring application. You simply type your help topics in the interface. You can add images, as well as links, and when you’re done, you can output HTML, a JavaHelp system, or a document that can be typeset using the LaTeX typesetting system. My complaint about HelpSetMaker is that the interface isn’t very intuitive. You’ll be looking at the online help quite a bit before you get the hang of it.

If you need to create help for multiple operating systems, a good choice for delivering the help is WebHelp. WebHelp is a method for delivering online help or documentation in a Web browser. Normally, a technical writer would use RoboHelp to create a WebHelp system. While there’s no version of RoboHelp for Linux, there is a DocBook style sheet (available from http://cvs.sourceforge.net/cgi-bin/viewcvs.cgi/
docbook/contrib/xsl/applethelp) that can generate a basic WebHelp system. For information on using the style sheet, see the tutorial at http://scottnesbitt.net/techdocs/
WebHelp_with_DocBook.html.

Word Processors

I rarely, if ever, use a word processor for writing documentation. But word processors are great for shorter documents that technical writers must often create—documents like release notes, white papers, and even technical marketing materials.

On Linux, the strongest word processors are OpenOffice.org Writer (www.openoffice.org) and TextMaker (www.softmaker.de). Both of these word processors are very robust, with excellent graphics-handling capabilities and solid import filters.

When using a word processor for any kind of writing, you should take the time to create a template, and then apply the template styles to your text. This will ensure that all of your documents retain a consistent look and feel.

Developer Documentation

Software developers don’t care about how to use software. They want to build it. And this often involves using code that someone else created. Documenting code is hard work—probably the toughest of all technical writing tasks.

Luckily, there are a number of excellent applications that generate source code documentation. These include Doxygen (www.stack.nl/~dimitri/doxygen), Doc++ (http://docpp.sourceforge.net), RoboDoc (www.xs4all.nl/~rfsber/Robo/robodoc.html), and Natural Docs (www.naturaldocs.org).

The developers you work with will have to properly comment the code for these applications to work properly. And you will have to add additional information and examples to the output from these tools, but using them makes documenting code a lot easier.

Other Tools

Technical writing isn’t just about writing. Creating documentation also involves working with graphics and illustrations, as well as capturing screen images.

If you need to edit images, The GIMP (www.gimp.org) is the tool on Linux. Not only does it have powerful image-editing capabilities, but it can also perform screen captures, for when you need to have an example of an application window.

Another small, useful tool for manipulating images and capturing screen shots is xv (www.trilon.com/xv/xv.html). While xv’s interface isn’t exactly pretty, it gets the job done quickly and easily.

For illustrations and flowcharts, some of the best Linux applications are Sodipodi (www.sodipodi.com), Dia (www.gnome.org/projects/dia), and Kivio (www.koffice.org/kivio). Each has powerful and flexible tools that you can use to create all sorts of diagrams. And each one can export files in a number of commonly used graphics formats.

* * *

As you can see, there are a large number of technical writing tools for Linux. And those mentioned in this article just scratch the surface. There are numerous document processors, markup languages, and other tools just waiting for the enterprising technical writer to check them out. Who knows? You just might find a hidden gem that can meet your documentation needs.