The preferred way to document part of the GNU system is to write a
manual in the Texinfo formatting language. See the Texinfo manual,
either the hardcopy, or the on-line version available through
info or the Emacs Info subsystem (C-h i).
Programmers often find it most natural to structure the documentation following the structure of the implementation, which they know. But this structure is not necessarily good for explaining how to use the program; it may be irrelevant and confusing for a user.
At every level, from the sentences in a paragraph to the grouping of topics into separate manuals, the right way to structure documentation is according to the concepts and questions that a user will have in mind when reading it. Sometimes this structure of ideas matches the structure of the implementation of the software being documented--but often they are different. Often the most important part of learning to write good documentation is learning to notice when you are structuring the documentation like the implementation, and think about 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 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.
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.
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.
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 exceptions.) Also Unix man pages use a particular format which is different from what we use in GNU manuals.
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 file 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 violations of law.
Go to the first, previous, next, last section, table of contents.