[erlang-questions] Rhetorical structure of code: Anyone interested in collaborating?

[Richard A. O'Keefe]

On 10/05/16 5:23 AM, Lyn Headley wrote:
> The editor has a keybinding for 'express puzzlement here.' Elder may
> discern the source of the puzzlement simply by observing its line of
> code in context (which elder's editor provides), or elder may need
> more information.
I don't think there is any doubt about it.  My own experience has been
that "I don't understand <this>" invariably merits the response "*what*
don't you understand about <that>".  It doesn't always *get* that
response.

Let me give you a personal example, which still rankles.

I happened to mention to someone (while I was still a Masters student)
that I didn't understand the difference between the cardinal numbers
and the ordinal numbers.  What I *meant* was
   "I don't understand why \aleph_0 + \aleph_0 = \aleph_0
    but \omega + \omega > \omega."
That is, what I didn't understand was why infinite cardinals and infinite
ordinals don't follow the same rules.  (Please, don't anyone explain it
to me now.  Thanks to the book "The Joy of Sets", I do understand it.)
The lecturer in question told me a little story:
   A little boy was helping his mother in the kitchen.
   He was counting beans as he put them into a bowl.
   His mother said "give me five beans, Johnny."
   He answered, "I don't remember which was five."
This of course demonstrated the difference between the *linguistic*
cardinal numbers and ordinal numbers, but was utterly useless for
helping me with my actual problem.  Worse still, it left me feeling
humiliated that anyone had thought I might not understand the
linguistic distinction.  I never expressed any kind of ignorance or
uncertainty in front of that lecturer again.

So actually, there is something worse than "elder" having to ask "youth"
what the puzzlement is about, and that's "elder" NOT asking, because
"elder" has unwarranted confidence that s/he knows already.
> Note that context includes the entire active question
> history, which helps elder reply with "not relevant to your question."
> Express puzzlement is a bit lazy on youth's part, so before submitting
> her question youth may annotate this event with language.

And why should we believe that "elder" is right?  I mean, in this scenario,
"elder" doesn't know for sure what "youth's" question IS.  And even if the
answer is not relevant to "youth's" immediate *question*, it might be
extremely useful for youth's *development*.

It may be that other "elders" are extremely good at reading "youths'" minds.
Perhaps it is a form of clairvoyance.  It would be very interesting to 
explore
this experimentally.
>
> Youth 1 posts her question to a public location where Youth 2 and
> Google can trawl for existing questions and answers. Of course this
> raises Grzegorz Junka's question about how to maintain this archive,
> but I don't think maintenance is critical. The resource can age, even
> obsolesce, and still provide great value while it is relevant.

As always, the problem is knowing which bits are relevant and which are not.
It's not a matter of simple age.  Myself, I would find trawling through Q&A
sessions a frustrating squandering of my time, when the same amount of
effort could have gone into straightforward stuff in the source files.  I
would view it as other people viewing *their* time as far more valuable than
*my* time, because actually, it would be.
> I'll close with a grander claim. Programmers are less likely to add
> sufficient annotations and documentation to their code than they are
> to answer specific questions about the code.
Well, people are different.  The best programmers I've met (as in the ones
who could solve complex problems quickly and effectively) produced lots of
internal documentation.  And I really don't see why answers to specific
questions cannot be recorded *in the code*.

>   And this Q&A process can
> become a kind of re-usable documentation over time.

If it is not being maintained, so that it's not even trustworthy applied
to the file it pertains to, how is it going to become reusable?

If I *want* documentation in the form of questions and answers,
I know where to find StackOverflow.  I've even answered some
questions there myself.

The screen-capture-as-video-with-audio-questions experiment could
also be used to study whether people *are* good mind-readers about
what the question is.  (Turn off the audio, have the "elders" guess
what the question is, turn it back on and resume.)

The experiment might be worth doing.  Has anyone already done it?