[erlang-questions] Apology

Mark Nijhof mark.nijhof@REDACTED
Tue Sep 20 10:39:35 CEST 2016


I think one problem with the Erlang docs is that nobody does this:

"However, I am assuming this was not clear so I have opened an issue to fix
that in future releases."
On Tue, 20 Sep 2016 at 10:26, José Valim <jose.valim@REDACTED>
wrote:

>
>
>> 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.
>
> _______________________________________________
> 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/6708f61f/attachment.htm>


More information about the erlang-questions mailing list