[erlang-questions] Erlang documentation -- a modest proposal

[Lloyd R. Prentice]

Hi Kenneth,

No doubt your experience and knowledge of Erlang fills in much of what you need to make perfect sense of what you read in the Erlang docs. But I wish you could put yourself in noobie-mind. 

I've spent three years working alone and diligently so with help now and again from folks on this list to master enough Erlang to do a necessary job of work. I have bought, read, and re-read all of the published Erlang programming books. I've read Joe Armstrong's book at least six times and still learn from it every time I open it up.

But I can't tell you how many hours I've lost trying to figure out how to use this function or that based on the Reference docs when an example or two might have cleared things up post haste.

Perhaps I'm less intelligent than the average newcomer to Erlang. But I can say that as good as they are in many ways, I believe the docs can be better. Indeed, I confess that the descriptions of not a few functions, and even entire modules, leave me cross-eyed. Am I the only one?

If I saw a healthy trend of newcomers becoming active in the Erlang community I wouldn't be as concerned. But I don't see it. 

I've made a modest proposal to address an issue noted by several folks on this thread. I'd welcome any other proposal and concrete action that make the docs more accessible to newcomers looking into Erlang.

In my experience and judgement, there are just too many valuable but hidden gems in this wonderful language called Erlang. Wish I knew enough to shed light, but I don't.

All the best,

Lloyd

Sent from my iPad

> On Sep 22, 2016, at 11:18 PM, Kenneth Lakin <kennethlakin@REDACTED> wrote:
> 
>> On 09/22/2016 05:55 PM, Loïc Hoguin wrote:
>> Examples are never a bad thing to have; at worst they provide no value
>> for the majority of people;
> 
> If they make the documentation hard to read and understand, they're
> definitely a net negative.
> 
> A web development buddy of mine and I were using some library whose
> documentation he thought was a _paragon_ of readability. The
> "documentation" took the form of a complete program that exercised
> _every_ part of the -somewhat large- library on the right half of the
> screen, and call-outs aligned with the lines that they commented on that
> provided bare-bones commentary on most (but not all) of the API calls on
> the left half of the screen.
> 
> That was the _entirety_ of the documentation. It was _garbage_.
> Type-annotated (but otherwise auto-generated) Doxygen documentation
> would have been more useful.
> 
>> Yes. Someone with no experience will always appreciate them.
>> 
>> Not to mention that "sorted" in Erlang has a very specific meaning,
>> which is not defined at all in the documentation for lists:sort/1
> 
> A link back to section 8.11 of the Reference Manual User's Guide might
> be nice there. OTOH, I've never cared about the minutiae of how
> lists:sort/1 sorts. It has always just Done A Reasonable Thing(TM).
> 
> Speaking of the User's Guide... -ideally- someone with no Erlang
> experience should first be reading the Reference Manual User's Guide
> along with the Getting Started Guide (or LYSE or something) to pick up
> the fundamentals, rather than the various module Reference Manuals. In
> my experience, reference manuals exist to quickly provide useful
> information to people who are already familiar with a language. They
> shouldn't be language primers, as primers serve another purpose and
> should be in another document.
> 
> 
> _______________________________________________
> erlang-questions mailing list
> erlang-questions@REDACTED
> http://erlang.org/mailman/listinfo/erlang-questions