I think one problem with the Erlang docs is that nobody does this:<br><br>"However, I am assuming this was not clear so I have opened an issue to fix that in future releases."<br><div class="gmail_quote"><div dir="ltr">On Tue, 20 Sep 2016 at 10:26, José Valim <<a href="mailto:jose.valim@plataformatec.com.br">jose.valim@plataformatec.com.br</a>> wrote:<br></div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex"><div dir="ltr"><div class="gmail_extra"><div class="gmail_quote"><div> </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex">You're comparing a user guide page from Erlang to a function reference page from Elixir. The equivalent Erlang page is <a href="http://erlang.org/doc/man/application.html" rel="noreferrer" target="_blank">http://erlang.org/doc/man/application.html</a></blockquote><div><br></div></div></div></div><div dir="ltr"><div class="gmail_extra"><div class="gmail_quote"><div>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.</div><div><br></div><div>For example, take this page:</div><div><br></div><div><a href="http://erlang.org/doc/design_principles/des_princ.html" target="_blank">http://erlang.org/doc/design_principles/des_princ.html</a><br></div><div><br></div><div>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?</div><div><br></div><div>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.</div><div><br></div><div>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.</div><div><br></div><div>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.</div></div></div></div><div dir="ltr"><div class="gmail_extra"><div class="gmail_quote"><div> <br></div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex">
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).</blockquote><div><br></div></div></div></div><div dir="ltr"><div class="gmail_extra"><div class="gmail_quote"><div>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.</div></div></div></div><div dir="ltr"><div class="gmail_extra"><div class="gmail_quote"><div><br></div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex">And not needing to go back at the top to select another function is very convenient.</blockquote><div><br></div></div></div></div><div dir="ltr"><div class="gmail_extra"><div class="gmail_quote"><div>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.</div><div><br></div></div></div></div>
_______________________________________________<br>
erlang-questions mailing list<br>
<a href="mailto:erlang-questions@erlang.org" target="_blank">erlang-questions@erlang.org</a><br>
<a href="http://erlang.org/mailman/listinfo/erlang-questions" rel="noreferrer" target="_blank">http://erlang.org/mailman/listinfo/erlang-questions</a><br>
</blockquote></div>