What manuals should and should not say

classic Classic list List threaded Threaded
10 messages Options
Reply | Threaded
Open this post in threaded view
|

What manuals should and should not say

Dirk Laurie-2
<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.

Reply | Threaded
Open this post in threaded view
|

Re: What manuals should and should not say

Paul E. Merrell, J.D.
On Fri, Feb 5, 2016 at 9:19 PM, Dirk Laurie <[hidden email]> wrote:

> 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.

I'll take an exception here. Assuming that by "novice" we mean someone
who has never written a single line of code in any language, I think
you drastically underestimate the distance between our novice's
knowledge and your own.

PIL is not a book for novices. They lack the vocabulary to understand
it or the manual. As an example, take a look at this excerpt from the
v. 5.3 Reference Manual:

>>>
The following strings denote other tokens:

     +     -     *     /     %     ^     #
     &     ~     |     <<    >>    //
     ==    ~=    <=    >=    <     >     =
     (     )     {     }     [     ]     ::
     ;     :     ,     .     ..    ...

<<<

That's the entire explanation of those tokens. I'm 3 or 4 years into
working with Lua and I still haven't the slightest glimmer what the
ellipsis is for. And unless I've missed it, that explanation is also
missing from PIL.

The Manual and PIL are riddled with terms that are basically
meaningless to a novice. With some terms, one can get a glimmer
courtesy of Google, but most often you get their meaning in other
programming languages and have to hope that the meaning is similar in
Lua.

We have precisely one book available that attempts to serve the needs
of novices. [1] That book is for Lua v. 5.1 and Wiley only recently
published an eBook version that enables enlarging the type enough for
those with even mild visual deficits to read.

The vocabulary barrier is only one reason that for a couple of years
now I've advocated (unsuccessfully) for an online version of the
reference manual that can be annotated, for example with links to
definitions, the relevant wiki tutorial sections, and to other
instructive material.

I'll also point out that this list is not inundated with posts by
novices seeking enlightenment. In my studied opinion, that is because
this is a list for expert programmers. Even after reading every post
for the last 3-4 years, way over half of the discussion on this list
is beyond my comprehension. To a novice reviewing the list archives,
that's as good as a sign reading, "don't bother us with amateur
questions."

That is not to suggest that the few novices who do stumble in are
treated with any discourtesy. But if there's a list or web site that
serves the needs of Lua novices, I've never found it.

Which all seems very strange to me for an interpreter and language
designed for embedding in and extending other programs. To me, the
need for introductory-level learning aids seems obvious.

But in summary, I disagree your concusion, "[c]riticism of the manual
on the grounds that parts of it may be obscure to a novice is
therefore not justified." The Manual and PIL are not
introductory-level information sources.

Best regards,

Paul

[1] Karl Jung & Aaron Brown, Beginning Lua Programming (2007),
<http://www.wiley.com/WileyCDA/WileyTitle/productCd-0470069171.html>.

--
[Notice not included in the above original message:  The U.S. National
Security Agency neither confirms nor denies that it intercepted this
message.]

Reply | Threaded
Open this post in threaded view
|

Re: What manuals should and should not say

Ross Berteig
On 2/5/2016 10:58 PM, Paul Merrell wrote:
> ....
> PIL is not a book for novices. They lack the vocabulary to understand
> it or the manual.

Novice programmers, no, not really. But novices in Lua, sure. The pair
together are a complete course in the Lua language. The wiki, this list,
and the Gems book provide a significant resource. The Lua tag at Stack
Overflow is also well tended by experts, including one of Lua's authors.

> As an example, take a look at this excerpt from the
> v. 5.3 Reference Manual:
>>>>
> The following strings denote other tokens:
>
>       +     -     *     /     %     ^     #
>       &     ~     |     <<    >>    //
>       ==    ~=    <=    >=    <     >     =
>       (     )     {     }     [     ]     ::
>       ;     :     ,     .     ..    ...
> <<<
> That's the entire explanation of those tokens. I'm 3 or 4 years into
> working with Lua and I still haven't the slightest glimmer what the
> ellipsis is for. And unless I've missed it, that explanation is also
> missing from PIL.

That list is from section 3.1. See the rest of chapter three for a
detailed breakdown that covers all of those tokens, most of which get
somewhere between a sentence and a whole section in section 3.4. The
ellipsis is defined in 3.4.11.

This is a good example of a property that well written reference manuals
have. They are terse. They don't repeat themselves. And the author of
each sentence generally is free to assume that you already have read and
understood every other sentence in the reference manual. In short, with
very few exceptions a good reference manual is a horrible textbook.

Similarly, PiL is not a reference manual, nor is it an introductory text
in programming. Although it is among the best of its breed. Over the
many years (I began learning C in '82 from the 1st edition of K&R) that
I've been programming, I have seen some real doozies.

--
Ross Berteig                               [hidden email]
Cheshire Engineering Corp.           http://www.CheshireEng.com/


Reply | Threaded
Open this post in threaded view
|

Re: What manuals should and should not say

Nagaev Boris
On Sat, Feb 6, 2016 at 10:53 AM, Ross Berteig <[hidden email]> wrote:

> On 2/5/2016 10:58 PM, Paul Merrell wrote:
>>
>> ....
>> PIL is not a book for novices. They lack the vocabulary to understand
>> it or the manual.
>
>
> Novice programmers, no, not really. But novices in Lua, sure. The pair
> together are a complete course in the Lua language. The wiki, this list, and
> the Gems book provide a significant resource. The Lua tag at Stack Overflow
> is also well tended by experts, including one of Lua's authors.
>
>> As an example, take a look at this excerpt from the
>> v. 5.3 Reference Manual:
>>>>>
>>>>>
>> The following strings denote other tokens:
>>
>>       +     -     *     /     %     ^     #
>>       &     ~     |     <<    >>    //
>>       ==    ~=    <=    >=    <     >     =
>>       (     )     {     }     [     ]     ::
>>       ;     :     ,     .     ..    ...
>> <<<
>> That's the entire explanation of those tokens. I'm 3 or 4 years into
>> working with Lua and I still haven't the slightest glimmer what the
>> ellipsis is for. And unless I've missed it, that explanation is also
>> missing from PIL.
>
>
> That list is from section 3.1. See the rest of chapter three for a detailed
> breakdown that covers all of those tokens, most of which get somewhere
> between a sentence and a whole section in section 3.4. The ellipsis is
> defined in 3.4.11.

I don't know what "ellipsis" stands for. I can't find the word in the manual.

> This is a good example of a property that well written reference manuals
> have. They are terse. They don't repeat themselves. And the author of each
> sentence generally is free to assume that you already have read and
> understood every other sentence in the reference manual. In short, with very
> few exceptions a good reference manual is a horrible textbook.
>
> Similarly, PiL is not a reference manual, nor is it an introductory text in
> programming. Although it is among the best of its breed. Over the many years
> (I began learning C in '82 from the 1st edition of K&R) that I've been
> programming, I have seen some real doozies.
>
> --
> Ross Berteig                               [hidden email]
> Cheshire Engineering Corp.           http://www.CheshireEng.com/
>
>



--


Best regards,
Boris Nagaev

Reply | Threaded
Open this post in threaded view
|

Re: What manuals should and should not say

Choonster TheMage
On 6 February 2016 at 21:28, Nagaev Boris <[hidden email]> wrote:
>
> I don't know what "ellipsis" stands for. I can't find the word in the manual.
>

An ellipsis is three dots (...), used in Lua to denote a vararg.

Reply | Threaded
Open this post in threaded view
|

Re: What manuals should and should not say

Sean Conner
In reply to this post by Paul E. Merrell, J.D.
It was thus said that the Great Paul Merrell once stated:

>
> PIL is not a book for novices. They lack the vocabulary to understand
> it or the manual. As an example, take a look at this excerpt from the
> v. 5.3 Reference Manual:
>
> >>>
> The following strings denote other tokens:
>
>      +     -     *     /     %     ^     #
>      &     ~     |     <<    >>    //
>      ==    ~=    <=    >=    <     >     =
>      (     )     {     }     [     ]     ::
>      ;     :     ,     .     ..    ...
>
> <<<
>
> That's the entire explanation of those tokens. I'm 3 or 4 years into
> working with Lua and I still haven't the slightest glimmer what the
> ellipsis is for. And unless I've missed it, that explanation is also
> missing from PIL.

  While the manual might be better off with an index or something at the end
that links to the definition of each function and operator, the information
*is* in the manual.  The token '..' is described in section 2.4 as the
concat operator.  The token '...' is described in section 3.4 as the
variable argument list (and are further described in section 3.4.11).

> The Manual and PIL are riddled with terms that are basically
> meaningless to a novice. With some terms, one can get a glimmer
> courtesy of Google, but most often you get their meaning in other
> programming languages and have to hope that the meaning is similar in
> Lua.

  Could you give a few examples?  A glossary might be nice to add as well to
the manual.

  -spc


Reply | Threaded
Open this post in threaded view
|

Re: What manuals should and should not say

Luiz Henrique de Figueiredo
>   While the manual might be better off with an index or something at the end
> that links to the definition of each function and operator

Such an index is available, but in a separate page:
        http://www.lua.org/manual/5.3/#index

Suggestions for a more complete index are welcome, especially if it uses
the existing anchors in manual.html.

Reply | Threaded
Open this post in threaded view
|

Re: What manuals should and should not say

Ross Berteig
On 2/6/2016 3:54 AM, Luiz Henrique de Figueiredo wrote:
> ....
> Suggestions for a more complete index are welcome, especially if it uses
> the existing anchors in manual.html.

An additional section in the index that lists all the metamethods
clearly would be helpful. It could be grouped into core and standard
libraries, and each name could link to the anchor in manual.html where
it is defined.

I'm not sure what tooling is used to generate the manual, but since it
does support index construction that ought to be relatively easy to add
and maintain.

--
Ross Berteig                               [hidden email]
Cheshire Engineering Corp.           http://www.CheshireEng.com/


Reply | Threaded
Open this post in threaded view
|

Re: What manuals should and should not say

Paul E. Merrell, J.D.
In reply to this post by Luiz Henrique de Figueiredo
On Sat, Feb 6, 2016 at 3:54 AM, Luiz Henrique de Figueiredo
<[hidden email]> wrote:
>>   While the manual might be better off with an index or something at the end
>> that links to the definition of each function and operator
>
> Such an index is available, but in a separate page:
>         http://www.lua.org/manual/5.3/#index
>
> Suggestions for a more complete index are welcome, especially if it uses
> the existing anchors in manual.html.

I'll contribute to that, having just learned where the definitions of
the reserved characters are. What format would you like to receive the
contributions in?

Paul


--
[Notice not included in the above original message:  The U.S. National
Security Agency neither confirms nor denies that it intercepted this
message.]

Reply | Threaded
Open this post in threaded view
|

Re: What manuals should and should not say

Luiz Henrique de Figueiredo
> > Suggestions for a more complete index are welcome, especially if it uses
> > the existing anchors in manual.html.
>
> I'll contribute to that, having just learned where the definitions of
> the reserved characters are. What format would you like to receive the
> contributions in?

Plain HTML as used in http://www.lua.org/manual/5.3/#index is fine. Thanks.