Section 2.6. Writing Documentation

2.6. Writing Documentation

An ideal product is so transparent that it needs (almost) no documentation. Software products that are as well-designed and well-implemented as this Platonic ideal are rare indeed, so documentation is an expected part of all products. Whether the documentation is a simple README file, a large manual that ships with the product, or interactive help available when the product is used, the contents still have to be written by somebody, usually a technical writer.

Chapter 8 takes the viewpoint that the documentation is part of the product and that there are plenty of similarities between writing software and writing documentation. For instance, large documents are made up of smaller ones; different parts of a document depend on other parts of the document; and both source code and natural-language documents can benefit from tools, whether they are compiler warning flags or spellcheckers.

Another similarity between software and documentation is that both are transformed from one file format into other file formats as part of being released. A source file is compiled to an executable. A document is often written in one source file format (such as Microsoft Word or FrameMaker) and then converted to another release format (such as HTML or PDF, Adobe's Portable Document Format) for use by the customer. Some commonly used documentation formats are discussed in Section 8.3 (HTML, PostScript, and PDF) and Section 8.5 (TEX, Texinfo, troff, and POD).

A different aspect of documentation is when it is intended for use by a project itself. An example of this is when the APIs (application programming interfaces) of different parts of a product are documented to help other developers use them. There are a number of tools, such as Javadoc, to help with this, and these are also examined in Section 8.8.

Chapter 8 also examines in more detail a variety of file formats and their related documentation environments, including raw text, FrameMaker, XML in DocBook and OpenOffice, and Microsoft Word.