[erlang-questions] Apology

[José Valim]

> You're comparing a user guide page from Erlang to a function reference
> page from Elixir. The equivalent Erlang page is
> http://erlang.org/doc/man/application.html


I agree with many on this thread. I find Erlang documentation excellent in
terms of completeness. I love the user guides and reference manuals. But
they are hard to discover and there is very little guidance on how they
should be consumed.

For example, take this page:

http://erlang.org/doc/design_principles/des_princ.html

Who is this guide written for? Does it have any pre-requisites? What am I
expected to learn by the end of it? If this is not the guide I am looking
for, where can I find other guides?

When talking about module and function references, there are other areas
for improvement. We don't have a search mechanism on the official docs and
that's problematic because modules are split throughout multiple
applications. I find myself constantly changing the URL in the address bar
in order to navigate between modules in different applications because it
is never clear how to do that from a given module page.

I am sure it is possible to do it and I have done that before but on every
day usage I still struggle with navigating the docs even after working on
Erlang for 5 years.

Another area that could be improved in the Erlang documentation is
including examples of using modules and functions. Even in essential
modules, such as the lists one, I would estimate only half of the functions
have actual examples. Links from the docs to the source code can be useful
for learning purposes and links from the docs to the documentation source
can help boost contributions.


> And I'll echo Kenneth, the Erlang one is definitely better in my opinion.
> I'm not even sure why the function is described twice in the Elixir docs
> (title and spec).


If you are trying to answer which one is better you are missing the point.
Instead look at Elixir docs (or any other project really) and see which
ideas you can borrow to improve the Erlang documentation.

And not needing to go back at the top to select another function is very
> convenient.


You can navigate all module functions using the sidebar on the left after
clicking on "Functions". However, I am assuming this was not clear so I
have opened an issue to fix that in future releases.
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://erlang.org/pipermail/erlang-questions/attachments/20160920/dc397826/attachment.htm>