[erlang-questions] Apology

Tue Sep 20 07:07:02 CEST 2016

Good documentation is designed for readability, that goes beyond just
content - it includes layout, organisation and definitely aesthetics. The
Erlang docs are a virtualized printout, not an interactive guide on how to
use a programming language.

Look at the difference in these two pages.

http://erlang.org/doc/design_principles/applications.html

vs

http://elixir-lang.org/docs/stable/elixir/Application.html

Why doesn't anyone ever mention that the docs just look crap? It's easy to
fix, and would make a massive difference on the impression new devs get
about Erlang. These days programmers have largely become accustomed to a
certain look and feel, and have an intuition on how to dig for what they're
trying to find which doesn't stem from a time when you would turn to the
back of the printout and scan down the index, apologies to the E///
greybeards in the list :P

The underlying issue of terse or inadequate explanation would take longer
to fix, I think allowing pull requests would be a big step forward. Also,
what's with the multiple PDFs - you have a user manual, getting started
guide, reference manual, probably more that I can't remember right now.
There has got to be a way to just combine these into a single portal that
all developers can refer back to.

Lots of good information has been kept in this mailing list, so mails from
it often come up in Google. Tell me, how quickly did you find the answer on
this page http://erlang.org/pipermail/erlang-questions/2007-May/026655.html
compared to this one
http://stackoverflow.com/questions/2065990/defining-erlang-functions-in-the-shell

I'm not a novice programmer - I had been coding for 10 years when I picked
up Erlang with a masters in Software Eng, and immediately fell in love with
the language, but with such an expert community behind it I think it's been
a while since somebody who didn't intimately understand everything about
Erlang in detail gave feedback on the experience for new developers.

On Tue, Sep 20, 2016 at 2:38 PM, Lloyd R. Prentice <lloyd@REDACTED>
wrote:

> 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
>
> _______________________________________________
> erlang-questions mailing list
> erlang-questions@REDACTED
> http://erlang.org/mailman/listinfo/erlang-questions
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://erlang.org/pipermail/erlang-questions/attachments/20160920/7a58d438/attachment.htm>