Chapter 18. Documentation

Explaining Your Code to a Web-Centric World

Table of Contents

Documentation Concepts
The Unix Style
The Large-Document Bias
Cultural Style
The Zoo of Unix Documentation Formats
troff and the Documenter's Workbench Tools
The Present Chaos and a Possible Way Out
Document Type Definitions
Other DTDs
The DocBook Toolchain
Migration Tools
Editing Tools
Related Standards and Practices
XML-DocBook References
Best Practices for Writing Unix Documentation

I've never met a human being who would want to read 17,000 pages of documentation, and if there was, I'd kill him to get him out of the gene pool.

-- Joseph Costello

Unix's first application, in 1971, was as a platform for document preparation — Bell Labs used it to prepare patent documents for filing. Computer-driven phototypesetting was still a novel idea then, and for years after it debuted in 1973 Joe Ossana's troff(1) formatter defined the state of the art.

Ever since, sophisticated document formatters, typesetting software, and page-layout programs of various sorts have been an important theme in the Unix tradition. While troff(1) has proven surprisingly durable, Unix has also hosted a lot of groundbreaking work in this application area. Today, Unix developers and Unix tools are at the cutting edge of far-reaching changes in documentation practice triggered by the advent of the World Wide Web.

At the user-presentation level, Unix-community practice has been moving rapidly toward ‘everything is HTML, all references are URLs’ since the mid-1990s. Increasingly, modern Unix help browsers are simply Web browsers that know how to parse certain specialized kinds of URLs (for example, ‘man:ls(1)’ interprets the ls(1) man page into HTML). This relieves the problems created by having lots of different formats for documentation masters, but does not entirely solve them. Documentation composers still have to grapple with issues about which master format best meets their particular needs.

In this chapter, we'll survey the rather unfortunate surfeit of different documentation formats and tools left behind by decades of experimentation, and we'll develop guidelines for good practice and good style.