What manuals should and should not say

[Dirk Laurie <dirk.laurie@...>]

<preface>
There have been several posts recently by various people to the
effect that the Lua manual is inaccurate, incomplete, etc. I have
generally not agreed with the assessment, and. getting more and
more impatient with the trend, occasionally allowed my annoyance
to spill over into the style of my reply, for which I apologize.

So this time I'll stand in front and wait for the rotten tomatoes instead
of throwing them.
</preface>

A manual for a computer program is a document whose goal is
to enable users of that program to use it correctly. This goal has
two not quite compatible sub-goals.

   1. Saying what the program does.
   2. Saying what the program is supposed to do.

In the case of open-source software, Goal 1 is much less important
than Goal 2. One can always, if one is so inclined, read the source
code. In the case of Lua, the really crucial parts (e.g. lopcodes.h)
are very well commented, but very little of that can be found in the
manual. The implication is clear: the documentation of the C library
called "Lua" consists of the manual plus the comments in the source.
There is in fact at least one instance in the Lua 5.3 manual where
the reader is explicitly directed to the source code.

Criticism of the manual on the grounds that one needs to read the
source code in order to get clarity on some point is therefore not
justified.

Goal 2 is important, particularly when the manual describes the
implementation of a computer language which has no other formal
specification. In this case, the manual approaches the status of
a standard for the language. It is precisely here that the manual
should say as little as possible; in the words of Martin Greenfield
in his essay on _The History of FORTRAN Standardization_,
"Once a feature was standardized, its life would be semi-eternal
even if the feature were a mistake." By and large the authors
have followed an (appropriately) unspoken rule: if something does
not need to be said, don't say it.

Criticism of the manual on the grounds that leaves some things
unspecified is therefore seldom justified.

One goal that the manual does not have is to teach a novice how
to program efficiently in Lua. The introduction to the manual directs
the reader to Roberto's book on the topic.

Criticism of the manual on the grounds that parts of it may be
obscure to a novice is therefore not justified.

So what grounds remain for criticizing the manual? Here is a checklist.

1. The critic has been personally inconvenienced. I.e. some time
was spent in debugging a program, including reading and rereading
the relevant parts of the manual.
2. The critic has been reading at a sufficiently alert level (e.g.
if the manual refers to t[1],t[2] etc, it is not a defect in the manual
if the reader fails to grasp that metamethods may come into play).
3. The inconvenience would have been less if some part of the
manual had been more precise or more complete.