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

[Richard A. O'Keefe]

On 7/05/16 6:06 AM, Lyn Headley wrote:
> I recently conceived a sociotechnical process that would help us
> understand each other's code. It is simple to implement. In bare bones
> it is this:
>
> I am new to your project. As I read your code, certain events are
> recorded by my editor and sent to a log that you are monitoring. You
> can easily browse the log, see where I am bumping into issues, and
> easily provide feedback.

One problem with this is that it is *syntactic*, not *semantic*.
The editor tells me *what* you are looking at, but not *why*
you are looking at it, not even whether it is what you *intended*
to look at or something you arrived at by accident.

And since we are (probably) on opposite sides of the planet, you are
most unlikely to be able to give me feedback at the time I need it.
> That's it.
>
> To put some flesh on it, you might see:
>
> Lyn jumped from file:line to function f/2 in file2.
> Lyn expressed puzzlement.

How does the editor know that Lyn expressed puzzlement?
Is it because the comment is in Māori, or because it looks as
though there might be a division by zero, or because this is
Python3 and Lyn is used to Python2?
> Your feedback could be in the context of this series of events as
> well. So when I receive it, I am reminded of exactly where I was. As
> feedback I see the annotated log:
>
> Lyn jumped from file:line to function f/2 in file2.
> Lyn expressed puzzlement.
> [Joe said: That's an optimization for X case].
>
> That's really it.  This is easy to write and I think it's a huge win.
> What do you think?
*What* is easy to write?
I think we need a lot more detail before it is possible to make
that judgement.

Possibly the easiest way to do this might be through some sort
of video screen capture with audio annotation, where Lyn *says*
she is puzzled, in which case it may be possible to try this out
using existing tools.

I think something like this is DEFINITELY worth trying.

It does have a downside.  I started this thread talking about
1 person leaving signposts (rhetorical structure annotations)
for N > 1 readers.  The editing log idea is 1:1; if Helen wrote
the code and Lyn recorded herself viewing it and Helen
replies to Lyn, that helps Lyn, but it doesn't help Sue, unless
she knows that Helen's reply to Lyn's session exists.