[erlang-questions] Erlang documentation

Loïc Hoguin <>
Tue Sep 20 11:27:23 CEST 2016


This is something that I believe the PHP documentation does best. Every 
function page features a changelog, for example: 
https://secure.php.net/manual/en/function.htmlentities.php#refsect1-function.htmlentities-changelog

Used to go back as far as PHP4; can't find any example of those at the 
moment, maybe it was dropped.

While I wouldn't rank PHP the language very high in my list of favorites 
(other than how insanely easy it is to get started with it, even for 
people with no programming experience), the PHP documentation has been 
the best documentation I ever used.

Out of the top of my head, in addition to the changelog, these are also 
very useful:

* One page per function; debatable, but useful to pack more information
* Detailed arguments and return values; not just typespecs (Erlang 
sometimes forces you to go up and down the page to find the full 
argument type, for example with the ssl module)
* Examples! Many many examples
* Related functions quickly discoverable; in the 'erlang' module it's 
hard to make out what relates to what
* Comments; love them or hate them, they're useful to many developers
* Input php.net/function-name in your browser and get the corresponding 
page directly

I also notice that the layout improved since the last time I used it, 
and it seems easier to navigate nowadays. The entire documentation is 
easily accessible with a few clicks from any page; can't say the same 
for Erlang (try finding the Design Principles from the ssl reference 
page). The search field is also always visible, regardless of scrolling.

I'm thinking I should get more inspiration from there for the Cowboy 2.0 
documentation, especially for the function reference. One page per 
function with greater details, examples and links to related functions 
would be a great improvement I believe.

On 09/20/2016 10:53 AM, Alin Popa wrote:
> 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 <
> <mailto:>> wrote:
>
>
>
>     On Tue, Sep 20, 2016 at 8:14 AM Kenneth Lakin
>     < <mailto:>> 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
>     <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
>     <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
>         <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
>          <mailto:>
>         http://erlang.org/mailman/listinfo/erlang-questions
>         <http://erlang.org/mailman/listinfo/erlang-questions>
>
>
>     _______________________________________________
>     erlang-questions mailing list
>      <mailto:>
>     http://erlang.org/mailman/listinfo/erlang-questions
>     <http://erlang.org/mailman/listinfo/erlang-questions>
>
>
>
>
> _______________________________________________
> erlang-questions mailing list
> 
> http://erlang.org/mailman/listinfo/erlang-questions
>

-- 
Loïc Hoguin
http://ninenines.eu
Author of The Erlanger Playbook,
A book about software development using Erlang


More information about the erlang-questions mailing list