Creating professional documentation with Linux tools
by: Scott Nesbitt
© 2008 DMN Communications Ltd.
Originally published at Linux.com on May 12, 2006
|
Creating professional documentation with Linux toolsby: Scott Nesbitt© 2008 DMN Communications Ltd. |
Documentation is a necessary evil of software development. While Linux lacks standard Windows tools such as FrameMaker, RoboHelp, and WebWorks Publisher, it's still a viable environment for technical writers. Linux users can take advantage of a number of documentation tools, including both free or open source software (FOSS) and proprietary software. All of them give technical writers the ability to author and publish professional documentation.
You can, for example, run FrameMaker 5.5.2 or 6.0 or Word in Linux using CrossOver Office or WINE. But some Linux users might not want to do this, either because of the cost or because they want to stick with using only free or Open Source software (FOSS).
While there is a dearth of graphical Linux documentation tools, technical writers have a wide range of other documentation software at their disposal. In the right hands, this software can be used to create high-quality documentation.This article introduces a number of Linux tools for technical writers. Most are FOSS, while some are proprietary software. But all of them give technical writers working in Linux the ability to author and publish professional documentation.
DocBook XML isn't an application, but it 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.
One of DocBook's strengths is that you can use it to output documentation in multiple formats, including PDF and PostScript (for printing), HTML, and HTML Help and JavaHelp. You can also author multiple documents that contain much of the same content, but which are intended, for example, for different users or different operating systems. This enables you to maintain all of your information in one file rather than having to maintain multiple documents.
Since DocBook files are XML, you can edit them in any XML or text editor. Some writers use Emacs with the psgml-x or nxml packages. Others use gvim, along with a script or two. This tutorial also explains how to use gvim as a DocBook editor. Vex, an XML editor based on the Eclipse programmer's tool, is an excellent DocBook editor as is XXE, a WYSIWYG editor written in Java.
You produce output by applying XSL stylesheets to your files 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 or xsltproc. To create PDF, Postscript, or RTF files, you first run your document through an XSL processor and then through an XSL-FO processor like the free FOP or the commercial XEP. Both FOP and XEP are command line tools. If you want to go GUI, then look at XFC which combines an XSL processor and a XSL-FO processor in a point-and-click package.
DITA is short for the Darwin Information Typing Architecture. Over the last couple of years, DITA has been attracting a lot of attention among technical writers. So much so that it's started 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 can be combines and reused in different types of documentation and in different delivery formats. While you can use DITA to create just about any kind of documentation, it's best suited for Web content, online help, computer-based training, and knowledge bases and FAQs.
Because DITA is based on XML, you can use any text or XML editor to author DITA documents. I was surprised to find several editing tools that both support DITA and run on Linux. The first is my text editor of choice, Emacs in conjunction with psgml-x. The same one that I use to write using DocBook. XXE also supports DITA, although the current version can't convert DITA documents to other formats. On top of that, 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.
Not everyone wants to read or even thumb through a manual. They want to press <F1> and get help. While Linux help authoring tools can't compare to their Windows counterparts, there are several strong Linux tools for developing online help.
A popular application is QuickHelp. 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 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 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 complaint about major 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. The WebHelp format -- HTML plus Java and Javascript -- was popularized by the folks who created RoboHelp, but the term is often used as a catch-all term for browser-based online help systems. Normally, a technical writer would use a tool like RoboHelp, AuthorIT, or MadCap Flare to create a WebHelp-like system. While there's no version of RoboHelp for Linux, there is a DocBook style sheet that can generate a basic WebHelp system. For information on using the style sheet, see this short tutorial.
I rarely, if ever, 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 must often create, like release notes, white papers, and even technical marketing materials.
On Linux, the strongest word processors are OpenOffice.org Writer and TextMaker. Both of these word processors are very robust, with excellent graphics-handling capabilities, flexible templates, solid import filters, and the ability to generate PDFs without any 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 I've never found AbiWord to be 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, 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.
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. In fact, it's probably the toughest of all technical writing tasks.
Luckily, there are a number of excellent applications that generate source code documentation. These include Doxygen, Doc++, RoboDoc, and Natural Docs. All 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 job for your. 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. Still, using them makes documenting code a lot easier.
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 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 editor consider is Krita, the image editor that is part of the KOffice suite.
Another small, useful tool for manipulating images and capturing screen shots is xv. While xv's interface isn't pretty, 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 Windows 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.
There are a large number of technical writing tools for Linux. While most of these tools aren't on par with the major Windows technical writing applications for features and ease of use, these tools are better than just good enough.
The software mentioned in this article only touches on the major Linux technical writing tools. There are also 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.
