[erlang-questions] Erlang documentation (was: Apology)

[Ali Sabil]

On Tue, Sep 20, 2016 at 8:14 AM Kenneth Lakin <kennethlakin@REDACTED>
wrote:

> On 09/19/2016 10:07 PM, Luke wrote:
> > Why doesn't anyone ever mention that the docs just look crap?
>
> I'm fond of how the docs look and -for the most part- reasonably pleased
> with how they're organized. (In particular, the /doc/man/$MODULE.html
> structure is _absolutely killer_ for reference documentation.) IMO, the
> quality and general completeness of the Erlang reference manuals is what
> most projects should strive to emulate in their API documentation.
>
>
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:
https://gist.github.com/asabil/76b30360afd4fec453b377e3e8ba77cc

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:
https://gist.github.com/asabil/76b30360afd4fec453b377e3e8ba77cc#gistcomment-1878283

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.


> > These days programmers have largely become accustomed to a
> > certain look and feel...
>
> I _really_ don't like how a _lot_ of "modern" documentation is laid out.
> If you're looking for inspiration, a _really_ impressive reference
> manual + user's guide (that -undoubtedly- took a _ton_ of work to put
> together) is the Postgresql documentation.
>
> Agreed, the PostgreSQL documentation is great, and we should aim for
something similar.



> > I think allowing pull requests would be a big step forward.
>
> https://github.com/erlang/otp/pulls
>
> I know for a fact that documentation updates are accepted. :)
>

I tried and I failed :/ The current documentation is built with magic,
maybe I should try again?


> _______________________________________________
> erlang-questions mailing list
> erlang-questions@REDACTED
> http://erlang.org/mailman/listinfo/erlang-questions
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://erlang.org/pipermail/erlang-questions/attachments/20160920/a92496bd/attachment.htm>