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

[Alin Popa]

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
http://erlang.org/doc/man/ets.html#update_counter-4; and unless I'm missing
something, it doesn't say when it was added).

Alin

On Tue, Sep 20, 2016 at 9:28 AM, Ali Sabil <ali.sabil@REDACTED> wrote:

>
>
> 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/76b30360afd4fec453b377e3e8ba77
> cc#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
>>
>
> _______________________________________________
> 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/b5219e5d/attachment.htm>