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

lloyd@REDACTED lloyd@REDACTED
Mon Sep 26 18:41:40 CEST 2016


Joe,

You've said so well what I've been trying to harp on.

My most recent timesink has been trying to understand xmerl sufficiently well to pull book data out of several different book APIs. Dave Thomas's 2007 tutorial has been a big help, but the black holes in my understanding still significantly impede my progress. So far I've spent maybe 10 to 15 hours trying to scope it out. I can get much of what I need from Amazon's APIs, but I need a redundant source. The Library of Congress API completely eludes me; I get a little further with ISBNdb, but still not far enough. 

Given discussion on the documentation thread to date, it seems to me that there are four issues at stake: 

1) Content deficiencies
2) Formatting issues
3) Lack of consensus of what we, as a community, want
4) How we move forward toward comprehensive improvement of documentation. 

Lukas Larsson's most recent post makes a good point.

Bruce Yinhe tells me in a private post that his group is about to hire one person on a part-time basis to  work on documentation improvements.

I've lost it in the thread, but as I recall we had some promising interest in documentation improvements from an Erricson employee.

It would be great if we could begin to rally around these comments and find some kind of convergence toward progress.

My take is to break the large task down into small chunks, bring the intelligence and resources of the community to bear on one specific issue at a time and, and get it done.

I don't have the technical chops, but I'll gladly work with you or anyone else to address content issues on a module-by-module basis. I can ask Micky-the_Dunce questions and, perhaps, help clarify language. It would be great if you could help clarify intent and application issues.

All the best,

Lloyd








-----Original Message-----
From: "Joe Armstrong" <erlang@REDACTED>
Sent: Monday, September 26, 2016 6:42am
To: "Lukas Larsson" <lukas@REDACTED>
Cc: "Lloyd R. Prentice" <lloyd@REDACTED>, "erlang-questions@REDACTED" <erlang-questions@REDACTED>
Subject: Re: [erlang-questions] Erlang documentation -- a modest proposal

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
>





More information about the erlang-questions mailing list