[erlang-questions] Erlang documentation (was: Apology)
Tue Sep 20 10:53:26 CEST 2016
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).
On Tue, Sep 20, 2016 at 9:28 AM, Ali Sabil <> wrote:
> On Tue, Sep 20, 2016 at 8:14 AM Kenneth Lakin <>
>> 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:
> 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.
>> 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 mailing list
-------------- next part --------------
An HTML attachment was scrubbed...
More information about the erlang-questions