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

[Lukas Larsson]

Hello,

On Thu, Sep 22, 2016 at 11:56 PM, Lloyd R. Prentice <lloyd@REDACTED>
wrote:

> Hello,
>
> To date, this thread has generated quite a few worthwhile insights and
> ideas. My fear is that they will be deep-sixed into the archive. On the
> other hand, major revision is a daunting task and unlikely to happen.
>
> But maybe we can focus on specific issues and make iterative headway.
>
> Fewer than half of the functions in the lists library, for instance, have
> code examples. Suppose over the span of one week we were collectively focus
> on generating at least two code examples for each function in one library.
>
> At the end of the week we could organize the submissions and vote on best
> candidates for inclusion in the docs. That done, we can pick another module.
>
> Thus, with not much effort from any one individual, a small posse of
> volunteer Erlang wizards could make short work of deficiencies in the docs.
>
> Anyway, it's an idea.
>
> All the best,
>
> LRP
>
>
I think that it is great to see everyone talking about wanting to improve
the documentation. The contributions to the Erlang/OTP project that I value
that most are documentation changes that make the intention clearer, or
explains some corner case somewhere which the docs did not initially
mention.

Unfortunately, once one has figured out how a function works there seems to
be very little incentive to make the docs clearer. I would estimate that
about every 20th pull request we get is a documentation fix, and more than
half of those are fixes of speling misstakes (which are great!).

I've just come back from about two weeks of vacation and this discussion
has resulted in roughly 0 pull requests for changes in the documentation.
Would it be possible to steer this discussion into doing something instead
of talking about doing something? Yes the technology/layout is not perfect,
but as Loïc said, it is the content that matters the most.

Lukas
// my own oppinions
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://erlang.org/pipermail/erlang-questions/attachments/20160926/12ef9714/attachment.htm>