Re: Introduction

[Ben Pfaff]

Jason Stover <address@hidden> writes:

> As long as we are on the topic of the manual, I read a suggestion a
> while ago for how to organize a good manual. Unfortunately, I can't
> find the reference now, but if I remember correctly, it said a manual
> should contain about five sections: Introduction, tutorial, syntax
> definition, and a couple of others I can't remember.  It looked good
> at the time, anyway. Does anyone know whose idea this was (and what
> the sections were)?

The GNU standards guide has some advice:

       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.

...

       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 list 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
    *Note Making Index Entries: (texinfo)Index Entries, and see *Note
    Defining the Entries of an Index: (texinfo)Indexing Commands.

...

       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.


-- 
Ben Pfaff 
http://benpfaff.org