6.1 GNU Manuals

The preferred document format for the GNU system is the Texinfo formatting language. Every GNU package should (ideally) have documentation in Texinfo both for reference and for learners. Texinfo makes it possible to produce a good quality formatted book, using TeX, and to generate an Info file. It is also possible to generate HTML output from Texinfo source. See the Texinfo manual, either the hardcopy, or the on-line version available through info or the Emacs Info subsystem (C-h i).

Nowadays some other formats such as Docbook and Sgmltexi can be converted automatically into Texinfo. It is ok to produce the Texinfo documentation by conversion this way, as long as it gives good results.

Make sure your manual is clear to a reader who knows nothing about the topic and reads it straight through. This means covering basic topics at the beginning, and advanced topics only later. This also means defining every specialized term when it is first used.

Remember that the audience for a GNU manual (and other GNU documentation) is global, and that it will be used for years, maybe decades. This means that the reader could have very different cultural reference points. Decades from now, all but old folks will have very different cultural reference points; many things that "everyone knows about" today may be mostly forgotten.

For this reason, try to avoid writing in a way that depends on cultural reference points for proper understanding, or that refers to them in ways that would impede reading for someone that doesn’t recognize them.

Likewise, be conservative in your choice of words (aside from technical terms), linguistic constructs, and spelling: aim to make them intelligible to readers from ten years ago. In any contest for trendiness, GNU writing should not even qualify to enter.

It is ok to refer once in a rare while to spatially or temporally localized reference points or facts, if it is directly pertinent or as an aside. Changing these few things (which in any case stand out) when they no longer make sense will not be a lot of work.

By contrast, it is always proper to refer to concepts of GNU and the free software movement, when they are pertinent. These are a central part of our message, so we should take advantage of opportunities to mention them. They are fundamental moral positions, so they will rarely if ever change.

Programmers tend to carry over the structure of the program as the structure for its documentation. But this structure is not necessarily good for explaining how to use the program; it may be irrelevant and confusing for a user.

Instead, the right way to structure documentation is according to the concepts and questions that a user will have in mind when reading it. This principle applies at every level, from the lowest (ordering sentences in a paragraph) to the highest (ordering of chapter topics within the manual). Sometimes this structure of ideas matches the structure of the implementation of the software being documented—but often they are different. An important part of learning to write good documentation is to learn to notice when you have unthinkingly structured the documentation like the implementation, stop yourself, and look for better alternatives.

For example, each program in the GNU system probably ought to be documented in one manual; but this does not mean each program should have its own manual. That would be following the structure of the implementation, rather than the structure that helps the user understand.

Instead, each manual should cover a coherent topic. For example, instead of a manual for diff and a manual for diff3, we have one manual for “comparison of files” which covers both of those programs, as well as cmp. By documenting these programs together, we can make the whole subject clearer.

The manual which discusses a program should certainly document all of the program’s command-line options and all of its commands. It should give examples of their use. But don’t organize the manual as a list of features. Instead, organize it logically, by subtopics. Address the questions that a user will ask when thinking about the job that the program does. Don’t just tell the reader what each feature can do—say what jobs it is good for, and show how to use it for those jobs. Explain what is recommended usage, and what kinds of usage users should avoid.

In general, a GNU manual should serve both as tutorial and reference. It should be set up for convenient access to each topic through Info, and for reading straight through (appendixes aside). A GNU manual should give a good introduction to a beginner reading through from the start, and should also provide all the details that hackers want. The Bison manual is a good example of this—please take a look at it to see what we mean.

That is not as hard as it first sounds. Arrange each chapter as a logical breakdown of its topic, but order the sections, and write their text, so that reading the chapter straight through makes sense. Do likewise when structuring the book into chapters, and when structuring a section into paragraphs. The watchword is, at each point, address the most fundamental and important issue raised by the preceding text.

If necessary, add extra chapters at the beginning of the manual which are purely tutorial and cover the basics of the subject. These provide the framework for a beginner to understand the rest of the manual. The Bison manual provides a good example of how to do this.

To serve as a reference, a manual should have an Index that lists all the functions, variables, options, and important concepts that are part of the program. One combined Index should do for a short manual, but sometimes for a complex package it is better to use multiple indices. The Texinfo manual includes advice on preparing good index entries, see Making Index Entries in GNU Texinfo, and see Defining the Entries of an Index in GNU Texinfo.

Don’t use Unix man pages as a model for how to write GNU documentation; most of them are terse, badly structured, and give inadequate explanation of the underlying concepts. (There are, of course, some exceptions.) Also, Unix man pages use a particular format which is different from what we use in GNU manuals.

Please include an email address in the manual for where to report bugs in the text of the manual.

Please do not use the term “pathname” that is used in Unix documentation; use “file name” (two words) instead. We use the term “path” only for search paths, which are lists of directory names.

Please do not use the term “illegal” to refer to erroneous input to a computer program. Please use “invalid” for this, and reserve the term “illegal” for activities prohibited by law.

Please do not write ‘()’ after a function name just to indicate it is a function. foo () is not a function, it is a function call with no arguments.

Whenever possible, please stick to the active voice, avoiding the passive, and use the present tense, not the future tense. For instance, write “The function foo returns a list containing a and b” rather than “A list containing a and b will be returned.” One advantage of the active voice is it requires you to state the subject of the sentence; with the passive voice, you might omit the subject, which leads to vagueness.

It is proper to use the future tense when grammar demands it, as in, “If you type x, the computer will self-destruct in 10 seconds.”