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

[Kenneth Lakin]

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.


-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 819 bytes
Desc: OpenPGP digital signature
URL: <http://erlang.org/pipermail/erlang-questions/attachments/20160922/c9edcca4/attachment.bin>