Author: Scott Nesbitt
DocBook XML
The DocBook Project isn’t an application, but it is arguably the biggest gun in the Linux technical writing arsenal. It’s a variant of XML designed specifically for authoring software and hardware manuals. You can use DocBook to output documentation in multiple formats, including PDF and PostScript (for printing), HTML, HTML Help, and JavaHelp. You can also author multiple documents that contain much of the same content, but which are intended for different users or different operating systems. This enables you to maintain all of your information in one file rather than in multiple documents.
Since DocBook files are XML, you can edit them in any XML or text editor. Some writers use Emacs with the psgmlx or nXML packages. Others use Vim, along with a script or two. A tutorial explains how to use Vim as a DocBook editor. Vex, an XML editor based on Eclipse, is an excellent DocBook editor, as is XMLmind XML Editor (XXE), a WYSIWYG editor written in Java.
You produce output in DocBook by applying XSL stylesheets to your files using an XSL processor. The stylesheet determines the output format, and the XSL processor does the grunt work. For most formats, you can use an XSL processor such as the popular Saxon or xsltproc. To create PDF, PostScript, or RTF files, first run your document through an XSL processor and then through an XSL Formatting Objects (XSL-FO) processor such as the free Formatting Objects Processor (FOP) or the commercial RenderX XEP Engine. Both FOP and XEP are command-line tools. If you want to go GUI, then look at XMLmind FO Converter (XFC), which combines an XSL processor and an XSL-FO processor in a point-and-click package.
DITA
Over the last couple of years, Oasis Darwin Information Typing Architecture (DITA) has been attracting a lot of attention among technical writers — so much so that it’s starting to eat into the market share of DocBook. Rather than being based on the traditional book-chapter-section format, DITA is meant for creating individual topics that you can combine and reuse in different types of documentation and in different delivery formats. You can use DITA to create just about any kind of documentation, but it’s best suited for Web content, online help, computer-based training, knowledge bases, and FAQs.
Because DITA is based on XML, you can use any text or XML editor to author DITA documents. Several editing tools both support DITA and run on Linux. My text editor of choice is Emacs in conjunction with psgmlx, which is what I use with DocBook. XXE also supports DITA, although the current version can’t convert DITA documents to other formats. In addition, XXE lacks support for the DITA conref attribute, which enables you to reuse content by storing a reference to another DITA element.
Right now, the only way to convert a DITA document to a more usable format on Linux is with the DITA Open Toolkit for Linux. The Open Toolkit is easy to use and can transform DITA content to HTML, XHTML, PDF, Eclipse Help, or RTF.
Online help
Not everyone wants to read or even thumb through a manual. Some want to press F1 and get help. While Linux help authoring tools can’t compare to their Windows counterparts, several strong Linux tools can help you develop online help.
The popular application 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 is designed to deliver online help for software written in Java. It’s a powerful and flexible system, and Linux has several authoring tools available for creating JavaHelp systems. Two of these are JHelpDev and JHelp Builder, 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 is a graphical help authoring application that can output HTML, a JavaHelp system, or a document that can be typeset using LaTeX. You simply type your help topics in the interface, and you can add images as well as hyperlinks. My major complaint about HelpSetMaker is that the interface isn’t very intuitive. You’ll be looking at its online help quite a bit before you get the hang of it.
If you need to create help for multiple operating systems, consider WebHelp. WebHelp is a method for delivering online help or documentation in a Web browser. The WebHelp format — HTML plus Java and JavaScript — was popularized by Adobe’s Macromedia RoboHelp, but the term is often used as a catchall phrase for browser-based online help systems. Normally, a technical writer would use a tool such as RoboHelp, AuthorIT, or MadCap Flare to create a WebHelp-like system. While RoboHelp doesn’t have a Linux version, a DocBook stylesheet can generate a basic WebHelp system. For information on using the stylesheet, see this short tutorial.
Word processors
I rarely use a word processor for writing documentation. They’re not the greatest tools for handling large, often complex documents. But word processors are great for shorter documents that technical writers often must create, such as release notes, white papers, and even technical marketing materials.
On Linux, the strongest word processors are OpenOffice.org Writer and SoftMaker TextMaker. These robust word processors feature excellent graphics-handling capabilities, flexible templates, solid import filters, and the ability to generate PDF files without additional software. I’ve used both to write a number of shorter documents and have had no complaints.
Shops that are FOSS purists might balk at using TextMaker because it’s closed source software. A decent FOSS substitute is AbiWord. While AbiWord is not quite on par with TextMaker, its price is appealing. And for short documents, AbiWord does a solid job.
When using a word processor for any kind of writing, take the time to create a template, then apply the template styles to your text to ensure that all of your documents retain a consistent look and feel.
Developer documentation
For software developers, documenting code is hard work. In fact, it’s probably the toughest of all technical writing tasks.
Luckily, a number of excellent applications generate source code documentation. These include Doxygen, DOC++, ROBODoc, and Natural Docs. Each of these tools can generate documentation in multiple formats from multiple programming languages, including C/C++, Java, Perl, and IDL.
Source code documentation tools won’t do the whole job for you. Developers have to comment the code for these applications to work properly, and you must add information and examples to the output from these tools. Still, 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 is arguably the best tool on Linux. Not only does it have powerful image editing capabilities, but it can also perform screen captures for when you need an example of an application window. Another application to consider is Krita, the image editor that is part of the KOffice suite.
XV is another small, useful tool for manipulating images and capturing screenshots. XV’s interface isn’t pretty, but it gets the job done quickly and easily.
Other utilities that can take screen captures (and, in some cases, do more) include ImageMagick, KSnapshot, and xwd (the X Window System dump utility). In GNOME, you can take a screenshot using the Take Screenshot command under the System menu, or by pressing Alt-Print Screen on your keyboard.
For illustrations and flowcharts, some of the best Linux applications are Sodipodi, Dia, and Kivio. Each has powerful and flexible tools that you can use to create all sorts of diagrams. And each one can export files to a number of commonly used graphics formats.
The software mentioned in this article only touches on the major Linux technical writing tools. Numerous document processors, markup languages, and other tools are 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.
