<div dir="ltr">Worth mentioning that maybe there should be a version tag for each function/module saying when it was added? Happened to me few times already to realise that a particular function which was present in the documentation, was not available in my particular Erlang version, and I found out that only when running the tests (e.g. ets:update_counter/4 is not available in Erlang 17, but I can see it in here <a href="http://erlang.org/doc/man/ets.html#update_counter-4">http://erlang.org/doc/man/ets.html#update_counter-4</a>; and unless I'm missing something, it doesn't say when it was added).<div><br></div><div>Alin</div><div class="gmail_extra"><br><div class="gmail_quote">On Tue, Sep 20, 2016 at 9:28 AM, Ali Sabil <span dir="ltr"><<a href="mailto:ali.sabil@gmail.com" target="_blank">ali.sabil@gmail.com</a>></span> wrote:<br><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex"><div dir="ltr"><br><br><div class="gmail_quote"><span class=""><div dir="ltr">On Tue, Sep 20, 2016 at 8:14 AM Kenneth Lakin <<a href="mailto:kennethlakin@gmail.com" target="_blank">kennethlakin@gmail.com</a>> wrote:<br></div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">On 09/19/2016 10:07 PM, Luke wrote:<br>
> Why doesn't anyone ever mention that the docs just look crap?<br>
<br>
I'm fond of how the docs look and -for the most part- reasonably pleased<br>
with how they're organized. (In particular, the /doc/man/$MODULE.html<br>
structure is _absolutely killer_ for reference documentation.) IMO, the<br>
quality and general completeness of the Erlang reference manuals is what<br>
most projects should strive to emulate in their API documentation.<br>
<br></blockquote><div><br></div></span><div>While I agree that the erlang documentation content is great, its structure is only good if you know what you are looking for, it is certainly lacking in discoverability, this is its current high level structure: <a href="https://gist.github.com/asabil/76b30360afd4fec453b377e3e8ba77cc" target="_blank">https://gist.<wbr>github.com/asabil/<wbr>76b30360afd4fec453b377e3e8ba77<wbr>cc</a></div><div><br></div><div>It is split in 3 different groups (Erlang/OTP, Applications and ERTS), which makes sense when you know what each one of them means. But for newcomers I think that the documentation fails at holding hands and walking you through the zoo that Erlang/OTP is :) My initial suggestion would be something more like this:</div><div><a href="https://gist.github.com/asabil/76b30360afd4fec453b377e3e8ba77cc#gistcomment-1878283" target="_blank">https://gist.github.com/<wbr>asabil/<wbr>76b30360afd4fec453b377e3e8ba77<wbr>cc#gistcomment-1878283</a><br></div><div><br></div><div>The second issue with the Erlang documentation is the visual aspect of it: it just feels a bit outdated :/ The typography and spacing would definitely need some improvement, and so do the various diagrams and illustrations.</div><span class=""><div> </div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">
> These days programmers have largely become accustomed to a<br>
> certain look and feel...<br>
<br>
I _really_ don't like how a _lot_ of "modern" documentation is laid out.<br>
If you're looking for inspiration, a _really_ impressive reference<br>
manual + user's guide (that -undoubtedly- took a _ton_ of work to put<br>
together) is the Postgresql documentation.<br>
<br></blockquote></span><div>Agreed, the PostgreSQL documentation is great, and we should aim for something similar.</div><span class=""><div><br></div><div> </div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">
> I think allowing pull requests would be a big step forward.<br>
<br>
<a href="https://github.com/erlang/otp/pulls" rel="noreferrer" target="_blank">https://github.com/erlang/otp/<wbr>pulls</a><br>
<br>
I know for a fact that documentation updates are accepted. :)<br></blockquote><div><br></div></span><div>I tried and I failed :/ The current documentation is built with magic, maybe I should try again?</div><span class=""><div> </div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">
______________________________<wbr>_________________<br>
erlang-questions mailing list<br>
<a href="mailto:erlang-questions@erlang.org" target="_blank">erlang-questions@erlang.org</a><br>
<a href="http://erlang.org/mailman/listinfo/erlang-questions" rel="noreferrer" target="_blank">http://erlang.org/mailman/<wbr>listinfo/erlang-questions</a><br>
</blockquote></span></div></div>
<br>______________________________<wbr>_________________<br>
erlang-questions mailing list<br>
<a href="mailto:erlang-questions@erlang.org">erlang-questions@erlang.org</a><br>
<a href="http://erlang.org/mailman/listinfo/erlang-questions" rel="noreferrer" target="_blank">http://erlang.org/mailman/<wbr>listinfo/erlang-questions</a><br>
<br></blockquote></div><br></div></div>