[erlang-questions] Erlang documentation -- a modest proposal

[Gokhan Boranalp]

Greetings,

There should be some predefined categories of doc types;
1. Code
1.a. Clear listings of methods/classes with proper links to jump
whenever needed. check Java API[1].
1.b. Comments and basic usage examples for every single function within code.
1.c. Editor IDE helpers/plugins to show usage, autocomplete/jump from
one module/function to another.
1.d Proper error definitions to find wtf is wrong preferably connect
them to stackoverflow or http://lmgtfy.com/ to ask others.
1.e Pure proper error definitions to correctly trace, which module
screwed before this module spits bunch of tuples out to the console.
2. General help articles to explain more specific topic. Something
like gen_server explanation[2] etc.
3. Tutorial style, story based help starts with first step and follows
to last step to show coder how to do things.
4. Advocate articles. Someone writes how your language/toolset is "Det
bästa"[3] in several blogs.
5. Of course books.

As it can be seen clearly, they have a different purpose and there is
no orthogonal way to adjust all of them to the one place. Most of them
already ready but problem is, they are not organized in this way to
locate "easily".

I strongly propose to make clear doc category tree and rethink about
all documentation in all levels for "Det bästa" Erlang.

br

[1] https://docs.oracle.com/javase/7/docs/api/
[2] http://erlang.org/doc/man/gen_server.html
[3] https://translate.google.com/#sv/en/Det%20b%C3%A4sta

On Sat, Sep 24, 2016 at 8:50 PM, Robert Virding <rvirding@REDACTED> wrote:
> On 23 September 2016 at 11:17, Loïc Hoguin <essen@REDACTED> wrote:
>>
>> On 09/23/2016 10:36 AM, Lutz Behnke wrote:
>>>
>>> I would propose a position specific to the reference documentation:
>>>
>>> 8) Put the documentation in the source code. Use edoc (or similar new
>>> tool).
>>
>>
>> And I would strongly advise against that.
>>
>
> I definitely agree with Loïc here but from the programmers viewpoint. When
> working with the code I need (good) documentation which describes what the
> code is doing from the internal POV. I definitely DON'T need documentation
> for the user on how to use and what it means and examples and ... . That
> just clutters up the page for me writing/maintaining the code.
>
> Note that I am NOT saying the user doesn't need all that, the user
> definitely does need/require all that, but it should be somewhere else not
> mixed in with the code.
>
> Robert
>
>
> _______________________________________________
> erlang-questions mailing list
> erlang-questions@REDACTED
> http://erlang.org/mailman/listinfo/erlang-questions
>



-- 
BR,
\|/ Kunthar