Re: What manuals should and should not say

[Paul Merrell <marbux@...>]

On Fri, Feb 5, 2016 at 9:19 PM, Dirk Laurie <dirk.laurie@gmail.com> 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.]