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

[Joe Armstrong]

I think what I miss most are *examples*

I've just been reading the edoc manual pages for a program
called <XYZ> (name changed to avoid embarrassment)

The functions are well documented - they types are well documented
but I haven't a clue about which ORDER to call the functions

Imagine a file system.

We *document* the open, read, write, and close functions
but we don't say you have to open the file before we read it.
We dont say when we're done we have to close the file.

We don't say this because it is *obvious*

But for the module glonk, which exports, zizzle, taddle, glonk and plonk
it is NOT obvious. Yes sure you all know you have to call glonk 3 times
before calling plonk - but I don't know.

Thats why we need examples.

Often I search for a tutorial and find a ten line blog posting that
actually shows me how to use a library - this gets me started.

very short unit tests - placed inline are *very* useful

for example:

     "321" = lists:reverse("123")

The unit test *are* the examples - what we don't have is software that
parses the code, parses the documentation, parses the unit test
and munges all together into a form that is convenient to read.

I'm actually trying to write something like this now - hence my wails
of anguish over css.

Wish me luck

/Joe







On Mon, Sep 26, 2016 at 11:58 AM, 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
>