standards: GNU Manuals

1 
1 6.1 GNU Manuals
1 ===============
1 
1 The preferred document format for the GNU system is the Texinfo
1 formatting language.  Every GNU package should (ideally) have
1 documentation in Texinfo both for reference and for learners.  Texinfo
1 makes it possible to produce a good quality formatted book, using TeX,
1 and to generate an Info file.  It is also possible to generate HTML
1 output from Texinfo source.  See the Texinfo manual, either the
1 hardcopy, or the on-line version available through 'info' or the Emacs
1 Info subsystem ('C-h i').
1 
1    Nowadays some other formats such as Docbook and Sgmltexi can be
1 converted automatically into Texinfo.  It is ok to produce the Texinfo
1 documentation by conversion this way, as long as it gives good results.
1 
1    Make sure your manual is clear to a reader who knows nothing about
1 the topic and reads it straight through.  This means covering basic
1 topics at the beginning, and advanced topics only later.  This also
1 means defining every specialized term when it is first used.
1 
1    Programmers tend to carry over the structure of the program as the
1 structure for its documentation.  But this structure is not necessarily
1 good for explaining how to use the program; it may be irrelevant and
1 confusing for a user.
1 
1    Instead, the right way to structure documentation is according to the
1 concepts and questions that a user will have in mind when reading it.
1 This principle applies at every level, from the lowest (ordering
1 sentences in a paragraph) to the highest (ordering of chapter topics
1 within the manual).  Sometimes this structure of ideas matches the
1 structure of the implementation of the software being documented--but
1 often they are different.  An important part of learning to write good
1 documentation is to learn to notice when you have unthinkingly
1 structured the documentation like the implementation, stop yourself, and
1 look for better alternatives.
1 
1    For example, each program in the GNU system probably ought to be
1 documented in one manual; but this does not mean each program should
1 have its own manual.  That would be following the structure of the
1 implementation, rather than the structure that helps the user
1 understand.
1 
1    Instead, each manual should cover a coherent _topic_.  For example,
1 instead of a manual for 'diff' and a manual for 'diff3', we have one
1 manual for "comparison of files" which covers both of those programs, as
1 well as 'cmp'.  By documenting these programs together, we can make the
1 whole subject clearer.
1 
1    The manual which discusses a program should certainly document all of
1 the program's command-line options and all of its commands.  It should
1 give examples of their use.  But don't organize the manual as a list of
1 features.  Instead, organize it logically, by subtopics.  Address the
1 questions that a user will ask when thinking about the job that the
1 program does.  Don't just tell the reader what each feature can do--say
1 what jobs it is good for, and show how to use it for those jobs.
1 Explain what is recommended usage, and what kinds of usage users should
1 avoid.
1 
1    In general, a GNU manual should serve both as tutorial and reference.
1 It should be set up for convenient access to each topic through Info,
1 and for reading straight through (appendixes aside).  A GNU manual
1 should give a good introduction to a beginner reading through from the
1 start, and should also provide all the details that hackers want.  The
1 Bison manual is a good example of this--please take a look at it to see
1 what we mean.
1 
1    That is not as hard as it first sounds.  Arrange each chapter as a
1 logical breakdown of its topic, but order the sections, and write their
1 text, so that reading the chapter straight through makes sense.  Do
1 likewise when structuring the book into chapters, and when structuring a
1 section into paragraphs.  The watchword is, _at each point, address the
1 most fundamental and important issue raised by the preceding text._
1 
1    If necessary, add extra chapters at the beginning of the manual which
1 are purely tutorial and cover the basics of the subject.  These provide
1 the framework for a beginner to understand the rest of the manual.  The
1 Bison manual provides a good example of how to do this.
1 
1    To serve as a reference, a manual should have an Index that lists all
1 the functions, variables, options, and important concepts that are part
1 of the program.  One combined Index should do for a short manual, but
1 sometimes for a complex package it is better to use multiple indices.
1 The Texinfo manual includes advice on preparing good index entries, see
DONTPRINTYET 1 ⇒Making Index Entries (texinfo)Index Entries, and see *note1DONTPRINTYET 1 ⇒Making Index Entries (texinfo)Index Entries, and see ⇒
 Defining the Entries of an Index (texinfo)Indexing Commands.
1 
1    Don't use Unix man pages as a model for how to write GNU
1 documentation; most of them are terse, badly structured, and give
1 inadequate explanation of the underlying concepts.  (There are, of
1 course, some exceptions.)  Also, Unix man pages use a particular format
1 which is different from what we use in GNU manuals.
1 
1    Please include an email address in the manual for where to report
1 bugs _in the text of the manual_.
1 
1    Please do not use the term "pathname" that is used in Unix
1 documentation; use "file name" (two words) instead.  We use the term
1 "path" only for search paths, which are lists of directory names.
1 
1    Please do not use the term "illegal" to refer to erroneous input to a
1 computer program.  Please use "invalid" for this, and reserve the term
1 "illegal" for activities prohibited by law.
1 
1    Please do not write '()' after a function name just to indicate it is
1 a function.  'foo ()' is not a function, it is a function call with no
1 arguments.
1 
1    Whenever possible, please stick to the active voice, avoiding the
1 passive, and use the present tense, not the future teste.  For instance,
1 write "The function 'foo' returns a list containing A and B" rather than
1 "A list containing A and B will be returned."  One advantage of the
1 active voice is it requires you to state the subject of the sentence;
1 with the passive voice, you might omit the subject, which leads to
1 vagueness.
1 
1    It is proper to use the future tense when grammar demands it, as in,
1 "If you type 'x', the computer will self-destruct in 10 seconds."
1