[erlang-questions] Request feedback on example project

[Lloyd R. Prentice]

Three cheers, Craig, for focusing on clarity and quality of Erlang documentation. And apologies for the length of this post.

As a know-nothing with little experience when I first set foot on the Erlang learning curve, I can attest to the frustration and rage that ensues when insufficient or opaque documentation blocks progress toward understanding and mastery.

That said, in general, Erlang documentation is outstanding in its scope and detail. Let me express profound gratitude to the many who have labored to make it so. 

But there are holes and lapses. Here are a few that come to mind:

- Libraries that offer no clue as to what problems they solve and why one would want to use them
- lack of tutorials and working code that demonstrate how to use them
- documentation that is overly abstract, appealing perhaps to mathematicians, but gibberish to the literal-minded newbie

But I understand. Software documentation is damned difficult. Keeping code and docs in sync, providing sufficient detail for newbies without wasting the time of gurus, finding time and incentive to document all contribute to the challenge.

Why bother? I'd argue that the easier it is to learn and master a language the wider the adoption. The wider the adoption, the more vibrant the community. The more vibrant the community, the more innovative, richer, and more functional the language.

Thus, my suggestion toward better documentation is simply this: 

A simple, explicit, well-publicized, and widely adopted statement of documentation best practices with examples.

I know that tidbits exist in the corpus here and there. But they need to be pulled together and prominently displayed

So, Craig, thank you for moving the ball forward.

Best wishes,

LRP

P.S. Just so happens that I was looking for UUID code the other day.


Sent from my iPad

> On Feb 3, 2016, at 2:34 AM, zxq9 <zxq9@REDACTED> wrote:
> 
>> On 2016年2月3日 水曜日 08:33:28 you wrote:
>>> On Wed, Feb 3, 2016 at 8:10 AM, zxq9 <zxq9@REDACTED> wrote:
>>> 
>>> There should never be a chance where 0 > V because V is
>>> extracted from a match on bits:
>>> 
>>>    version({uuid, <<_:48, V:4, _:12, 2:2, _:62>>})
>>>            when V > 0 andalso V < 6 ->
>> 
>> V > 0 means that V can't be 0...
>> 
>>> Therefore the following should be just as safe:
>>> 
>>>    version({uuid, <<_:48, V:4, _:12, 2:2, _:62>>})
>>>            when V < 6 ->
>> 
>> ... therefore the modification is not safe.
> 
> Indeed!
> 
> <facepalm/>
> 
> ...coffee...
> _______________________________________________
> erlang-questions mailing list
> erlang-questions@REDACTED
> http://erlang.org/mailman/listinfo/erlang-questions