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

[Nuku Ameyibor]

i agree with  Lloyd .
i also spent countless hours when i was learning erlang  trying to
understand some functions and how to use them .


So you have a library module.
> There are
>  - source code
>  - documentation
>  - examples
>

source code can be even more confusing for a beginner as it may be written
in  a very compact way that a beginner may not understand at that point in
time although it may be crystal clear for others .
documentation does not contain examples for most functions so you are still
stuck .

the maps module is one example of a module which would be very easy for a
*newcomer* to use as all the functions have a short explanation followed by
an example usage scenario .





On Fri, Sep 23, 2016 at 5:30 AM, Richard A. O'Keefe <ok@REDACTED>
wrote:

>
>
> On 23/09/16 3:18 PM, Kenneth Lakin 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.
>>
>
> I can only say that I have found the occasional example in the Unix
> manual pages to be a lifesaver, and that the presence of examples in
> the R documentation has often made it straightforward to use something
> whose description was not particularly helpful.  I suppose I can also
> say that "show me a list of places where this method is called" has
> been extremely informative when working on Smalltalk, even though those
> aren't *crafted* examples.
>
> Examples *instead* of documentation would be a bad thing.
> Examples *mixed in with* documentation can be distracting.
>
> So you have a library module.
> There are
>  - source code
>  - documentation
>  - examples
> Thanks to the magic of hypertext, these things don't have to be in the
> same view.  One reason for separating them is that somethings an
> example *has* to be an example of several things, so it's nice that it
> can be pointed to from several places, rather than duplicated.
>
>
> _______________________________________________
> 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/20160923/06095c8e/attachment.htm>