Yet more about making sense

[Michael Turner]

> Learning Erlang _requires_ you to be open to new concepts and
> terminology.  Erlang is not Java. Erlang is not C.

Yes, but when the documentation uses *old* terminology (we all know what
"stdlib" implies from learning other languages), evoking *old*
concepts, it's going to confuse people.  Everybody already knows what a
library is.  Most of Erlang stdlib actually matches those
preconceptions.  But the reference manual itself says that stdlib has no
services, so stdlib doesn't even conform to the reference manual's own
definition of application.

Tell me there's even ONE good thing about that picture.  Really.  Go
ahead.  Defend it.  What's good about it?

I'm open to the idea of "application" meaning something more abstract
in Erlang.  But you know what?  You don't get to that until over
halfway through C&R, where they define what an *OTP* application is,
then say that the word  "application" will henceforth mean that.  I
don't know at what point it's introduced in Joe's book --
"application" doesn't even have a freestanding index entry.

I'm open to new terminology and new concepts.  I'm not very open to
people failing to clearly *re*-define terms that have more usual senses,
well before they are used routinely, as they are in the Reference Manual
TOC.

And I started using the Reference Manual long before I ran across
definitions of the term "application" in the OTP sense, in the books. 
So why would it occur to me to look under "Basic Applications" if I
was trying to get information about a string function?

> The terminology is explained quite well in the Erlang documentation.

IF you can find those explanations.  IF they are indexed properly.  IF
they are introduce in the right order.

> But effort on the side of the learner is actually mandatory.

Actually, it's not.  Most learners of Erlang aren't learning it for
their job.  Most are learning it out of personal interest.  It's not
mandatory for me to use Erlang for what I'm interested in.  The more
poorly the documentation is organized, the more likely it is I'll
switch to another language.  I can hardly be alone in this.

There'd be no job listings today for Python or Perl if it wasn't for
people taking those language up out of personal interest.

> This effort lies in reading the documentation and experimenting
> with the system to cement your understanding of the text.

You're explaining how to learn a programming language to someone who's
written non-trivial code in over half a dozen languages, one with
decades of experience.  What those decades of experience are telling me
is: Erlang's documentation needs some serious work.

> None of the programming language manuals I know are didactic
> texts. Well, saying that, I've just remembered the original
> Smalltalk books; they're pretty fine.

Probably because they realized that good writing is part of the sale.

Go click the link for the STDLIB pdf.  Start reading.  It has a
*one-line* introduction.  Then it dives straight into some small module,
chosen in no particular order, full of typos, and so obscure that it was
used for years without being included.

If you defocus your eyes, that PDF *looks* like the chapter of a properly
organized book.  But it's not.

> This does not mean we should not strive for great documentation.
> But simply stating that the current set is not good enough won't
> change that.

I didn't "simply state that it's not good enough."  I've pointed out
very specific problems.  I find very specific problems almost everywhere
I look in the Reference Manual.

> You don't get quality that way. If you, or someone you know,
> can help with rearranging the existing documentation such that
> it becomes qualitatively better, then please pitch in.

I'm going to.  But look, put yourself in my position.  Let's say
you've gotten interested in the very powerful programming language
Frob.  You've learned some of it, which hasn't been so hard because
you had already learned Lisp, Prolog, Smalltalk, Python and Perl, and
the tutorials aren't half-bad (excellent in places).  But the TOC for
the reference manual (which you're already starting to need after only
a few weeks, because the books and tutorials necessarily skim some
subjects) just seems unnecessarily newbie-hostile.  You point out that

  Frob/OTP Introduction
  Standard Library
  Progamming Tools
  OTP Administration

or something like that, would be a better top-level TOC organization, in
part because it avoids repeated use of a *redefined technical term*
("library") in the headings.  Because, you see, in Frob parlance, you
"library" actual means what most programmers mean by the term
"database".  But you don't learn distinction that until halfway
through Frob Programming and Programming Frob, the major titles on the
subject.  One of those books doesn't even have the term in its index.

And let's say you that, after making this suggestion, you mostly meet
objections like,

  "The Frob docs are great!  Hats off to the authors!"

  "There are lots of good books and tutorials now!"

  "Don't you know how to learn a difficult programming language?  You
need to have an open mind and it takes work!"

  "The present Reference Manual TOC is perfectly consistent within our
own conceptual framework."

How would you feel?  I think you'd be feeling how I feel right now. 
Admittedly, some other people have said some more sensible things than
the above.  And in that, there's some hope.

I've done a lot of programming in my life.  I've also done a lot of
proofreading and editing, helping people produce whole books in some
cases.  (Very recently, I've done editing on books for free, on
projects I like.)  I've published articles on a number of topics.  And
I like Erlang, I even submitted a patch to make it build on a
problematic platform (well, Kenji had to shepherd it the rest of the way
through), and that took me days of narrowing down the location in the
code because the bug trashed the stack, forcing me to "binary search"
the cause with printfs instead of using the debugger.

I'm willing to help on the documention.  I think I've got the chops,
both as as an editor and as a programmer.  I'm willing to do for free.

But one thing I don't do: I don't try to help people suffering from a
see-no-evil attitude.  That's just the road to burnout.

-michael turner