<div dir="ltr"><br><br><div class="gmail_quote"><div dir="ltr">On Tue, Sep 20, 2016 at 8:14 AM Kenneth Lakin <<a href="mailto:kennethlakin@gmail.com">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><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">https://gist.github.com/asabil/76b30360afd4fec453b377e3e8ba77cc</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">https://gist.github.com/asabil/76b30360afd4fec453b377e3e8ba77cc#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><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><div>Agreed, the PostgreSQL documentation is great, and we should aim for something similar.</div><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/pulls</a><br>
<br>
I know for a fact that documentation updates are accepted. :)<br></blockquote><div><br></div><div>I tried and I failed :/ The current documentation is built with magic, maybe I should try again?</div><div> </div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">
_______________________________________________<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/listinfo/erlang-questions</a><br>
</blockquote></div></div>