[erlang-questions] Erlang documentation
Loïc Hoguin
essen@REDACTED
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 <ali.sabil@REDACTED
> <mailto:ali.sabil@REDACTED>> wrote:
>
>
>
> On Tue, Sep 20, 2016 at 8:14 AM Kenneth Lakin
> <kennethlakin@REDACTED <mailto: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
> <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
> erlang-questions@REDACTED <mailto:erlang-questions@REDACTED>
> http://erlang.org/mailman/listinfo/erlang-questions
> <http://erlang.org/mailman/listinfo/erlang-questions>
>
>
> _______________________________________________
> erlang-questions mailing list
> erlang-questions@REDACTED <mailto:erlang-questions@REDACTED>
> http://erlang.org/mailman/listinfo/erlang-questions
> <http://erlang.org/mailman/listinfo/erlang-questions>
>
>
>
>
> _______________________________________________
> erlang-questions mailing list
> erlang-questions@REDACTED
> 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