<div dir="ltr"><div class="gmail_extra">Hello,</div><div class="gmail_extra"><br><div class="gmail_quote">On Thu, Sep 22, 2016 at 11:56 PM, Lloyd R. Prentice <span dir="ltr"><<a href="mailto:lloyd@writersglen.com" target="_blank">lloyd@writersglen.com</a>></span> wrote:<br><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">Hello,<br>
<br>
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.<br>
<br>
But maybe we can focus on specific issues and make iterative headway.<br>
<br>
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.<br>
<br>
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.<br>
<br>
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.<br>
<br>
Anyway, it's an idea.<br>
<br>
All the best,<br>
<br>
LRP<br><br></blockquote><div><br></div><div>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.</div><div><br></div><div>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!).</div><div><br></div><div>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.</div><div><br></div><div>Lukas</div><div>// my own oppinions</div></div></div></div>