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

[Gokhan Boranalp]

Greetings,

1. There should be fundamental agreement for classification of the
documentation. This discussion is good for me to see who is thinking
how about documentation types.
2.  To me XSLT is not *enough* to manage all aspects of documentation.
We are using sphinx[1] for a large Python project. I have never used
it with Erlang but i'll give a try and share results with community.
Not every part of the documentation should be done natively in same
language. I hope this way is more valuable rather then asking useless
additions.

[1]
http://www.sphinx-doc.org/en/stable/
https://pythonhosted.org/sphinxcontrib-erlangdomain/


On Mon, Sep 26, 2016 at 12:58 PM, Lukas Larsson <lukas@REDACTED> wrote:
> Hello,
>
> On Thu, Sep 22, 2016 at 11:56 PM, Lloyd R. Prentice <lloyd@REDACTED>
> wrote:
>>
>> Hello,
>>
>> To date, this thread has generated quite a few worthwhile insights and
>> ideas. My fear is that they will be deep-sixed into the archive. On the
>> other hand, major revision is a daunting task and unlikely to happen.
>>
>> But maybe we can focus on specific issues and make iterative headway.
>>
>> Fewer than half of the functions in the lists library, for instance, have
>> code examples. Suppose over the span of one week we were collectively focus
>> on generating at least two code examples for each function in one library.
>>
>> At the end of the week we could organize the submissions and vote on best
>> candidates for inclusion in the docs. That done, we can pick another module.
>>
>> Thus, with not much effort from any one individual, a small posse of
>> volunteer Erlang wizards could make short work of deficiencies in the docs.
>>
>> Anyway, it's an idea.
>>
>> All the best,
>>
>> LRP
>>
>
> I think that it is great to see everyone talking about wanting to improve
> the documentation. The contributions to the Erlang/OTP project that I value
> that most are documentation changes that make the intention clearer, or
> explains some corner case somewhere which the docs did not initially
> mention.
>
> Unfortunately, once one has figured out how a function works there seems to
> be very little incentive to make the docs clearer. I would estimate that
> about every 20th pull request we get is a documentation fix, and more than
> half of those are fixes of speling misstakes (which are great!).
>
> I've just come back from about two weeks of vacation and this discussion has
> resulted in roughly 0 pull requests for changes in the documentation. Would
> it be possible to steer this discussion into doing something instead of
> talking about doing something? Yes the technology/layout is not perfect, but
> as Loïc said, it is the content that matters the most.
>
> Lukas
> // my own oppinions
>
> _______________________________________________
> erlang-questions mailing list
> erlang-questions@REDACTED
> http://erlang.org/mailman/listinfo/erlang-questions
>



-- 
BR,
\|/ Kunthar