[erlang-questions] Apology

[Lloyd R. Prentice]

So, I'm relieved and pleased that this thread is veering in a constructive direction. And I salute Richard for giving it a nudge.

Erlang documentation has been a frequent topic of conversation for as long as I've been following this list. On the one hand colossal work has been invested by many to produce what we have. I, for one, extend hearty thanks. On the other hand, many of us find nitpicks that loom large when we're trying to solve a problem, turn to the docs, but don't find the guidance we're looking for and need. Given my limited programming experience, the docs have been far more helpful than not, but four things have now and again vexed me:

1. Lack of context; e.g. why a library or function is useful; what real world problems can I solve with it? In some cases there is discussion, but so technical it flies over my head.

2. Excessive abstraction/concision. This is great for folks with mathematics training and cast of mind. But my literary sensibilities go tilt.

3. Too few or less-than-clear illustrative code fragments

4. Insufficient guidance on how to think through and design non-trivial Erlang programs.

In some areas it feels like the docs were written to REMIND users of what they already know, e.g. as reference rather than teaching material. So, no doubt every one of my vexations may well reflect my personal lack of experience with both Erlang and other programming languages. 

So we're left with two hard problems:

1. What should we assume about the consumers of Erlang documentation? Perhaps these assumptions should be explicit throughout the docs.

2. How can we iteratively improve the docs given voluntary resources and busy lives?

One hypothesis:

1. Writing software documentation that serves every consumer and every need may well be an impossible task.

I have purchased and studied every one of the Erlang books and taken much from each of them. I also often search for tutorials to help understand this issue or that. But I think it's safe to assume that official Erlang docs are the first go-to place for folks with immediate questions that need answers.

And one last question:

1. Can improved documentation be an effective tool for expanding and invigorating the Erlang community?

All the best,

Lloyd


Sent from my iPad

> On Sep 19, 2016, at 10:26 PM, Richard A. O'Keefe <ok@REDACTED> wrote:
> 
> 
> 
> On 20/09/16 8:18 AM, Loïc Hoguin wrote:
>> As for the documentation being very clear, it's very subjective. Nothing
>> is ever "very clear" to everyone.
> 
> Fair point.
> There are actually two issues, of course.
> 
> FINDING the documentation is the first thing.
> Searching for "Erlang documentation" quickly turns up
> https://www.erlang.org/docs.
> That says
>  <a>Erlang Reference Manual - User's Guide</a>
>  A user's guide System principles and efficiency guide
> which looks like an editing error.  If you follow the
> link you find the reference manual, not the system
> principles or efficiency guide.
> A reference manual and user's guide being different
> things, it would be better if this said something like
> 
>  <a>Erlang Reference Manual</a>
>  Defines Erlang's syntax, built-in data types,
>  preprocessor, error handling, processes, and more.
> 
> It would also be better if when you clicked on the link
> it didn't say
> 
>  Erlang Reference Manual User's Guide
> 
> (which sounds like a user's guide to using the reference
> manual) but something like
> 
>  Erlang Reference Manual
>  {An abstract}
> 
> because the eye is drawn to the big blank space where
> there's just a copyright notice, rather than to the navbar.
> I can't speak for anyone else, but whenever I go to that
> page I have several nervous seconds while wondering if I've
> come to the right place.
> 
> I personally find it confusing that "Escape Sequences"
> comes after "Boolean" rather than after "String" or "Atom".
> 
> Perhaps the most helpful thing in
> https://www.erlang.org/docs
> is
>  <a>Learn You Some Erlang for Great Good!<a>
>  Learn You Some Erlang for Great Good! by Fred Hebert
>  is a beginner's book about Erlang, published in 2013.
>  It is available in paper copies and online.
> 
> I have a copy of that book.  While it is a good book
> for beginners, it isn't just for beginners.  I have to
> be honest here: when it first came out I *hated* the
> title.  Stupid, stupid, stupid.  "Don't judge a book
> by its cover!"  Actually reading the book taught me,
> well, not exactly stuff I hadn't found elsewhere, but
> how to *use* a lot of stuff I hadn't bothered with.
> Someone who reads that book will not be a beginner for long.
> 
> We are blessed with a lot of good books about Erlang.
> I don't want to rank them.  But I do think that the
> documentation page might want to draw special attention
> to this book because people CAN read it on-line.  For
> example, three clicks get to you an explanation of strings.
> 
> The second issue is UNDERSTANDING the documentation when
> you find it.  The problem for writers is striking a
> balance between being concise and being patronising.
> I remember putting a lot of effort into writing a
> document for the BSI/ISO Prolog committee explaining a
> particular issue and some alternatives, and being told
> that it had been completely ignored because it was too
> long.  There's a series of books, originally "The Little
> Lisper" which I personally experienced as offensively
> patronising (and so culture-bound it wasn't funny, though
> it tried to be).  Yet for many people it was an EXCELLENT
> introduction to Lisp and Scheme and they loved the humour.
> 
> The current reference manual tries to be reassuringly
> informal (for beginners) and timesavingly brief (for
> experienced users).  Perhaps these rôles should be
> split between two different documents?  Or maybe an
> idea from MTW https://en.wikipedia.org/wiki/Gravitation_(book)
> could be adopted:  the text of that book is divided into
> "Track 1" (beginner level) and "Track 2" (more advanced)
> and the corners of the pages are coloured so you know which
> is which.  (About 35 years after buying it, I'm still on
> track 1.  Sigh.  It's a great book for long flights: I am
> guaranteed *never* to finish it.  Sigh.)
> 
> Hey, maybe we could get Fred Hébert to write the
> "Erlang Reference Manual for Beginners" (:-).
> _______________________________________________
> erlang-questions mailing list
> erlang-questions@REDACTED
> http://erlang.org/mailman/listinfo/erlang-questions