An Overview of Linux Technical Writing Tools
© 2008 DMN Communications Ltd.
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, Flare, 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 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. 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.
DITA
Over the last couple of years, 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 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.
Lightweight markup languages
I’ve been using markup languages, in one form or another, since the mid 1990s. I find them to be both useful and convenient. Useful in that they’re flexible and are well suited for writing articles, reports, and the like. Convenient in that I don’t have to worry about formatting or page layout or anything like that.
One class of markup languages that I really find useful are lightweight markup languages. They’re simple, and use markup that’s similar to wiki syntax -- keyboard characters are used to define formatting. But are lightweight markup languages up to the task of creating documentation? It really depends on the markup language, what documentation you’re developing, and how you want to present your documents.
I won’t go into a discussion of the pros and cons of using lightweight markup languages for documentation. I’ve already done it in this blog post.
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. 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 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 that can generate a basic WebHelp system. I’ve also put together a tutorial on using the style sheet.
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 and TextMaker. 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, Doc++, RoboDoc, and Natural Docs.
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 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 application to 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 exactly 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 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 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.
