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

[Mr. T]

On Mon May 9 03:01:02 2016, Richard A. O'Keefe <ok@REDACTED> wrote:
>
> 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,

HANG ON...

>
> 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.

... I'd go further and say that this is a BRILLIANT, BRILLIANT, BRILLIANT idea!

I'm reminded of those audio-logs in sci-fi movies where a mad
scientist records running commentary of his experiments using a
hand-held reporter recorder. The hope being; should he keel over from
inhaling toxic fumes, other scientists who get hold of the logs should
be able to not only understand *what* he was doing but also *why*, and
possibly *where* he went wrong.

I would ABSOLUTELY use a tool allowed me to attach audio-logs to
coding session screen-scrapes as you describe especially if it were
somehow integrated into both an editor/IDE (so I could annotate as I
code without switching to another tool) and version-control (so I
could play back annotations for commits).

Even if v1.0 of such tool were for my own personal use only and not
necessarily designed for collaboration (issues you raise below), the
ability to *easily* archive the evolution of my own code --
mad-scientist-style -- would be worth a million bucks because it would
solve two problems I have:

1. Whilst commit messages in version control can somewhat be used
towards the same goal: When I'm in the zone I don't commit frequently
enough, so my commit messages frequently aren’t descriptive enough. So
I find myself having to look at all the commited code anyway.

2. I use something similar to Joe's "research" directories, but I find
myself not keeping the notes therein up-to-date because of the time it
takes.

However, if all I have to do is speak, I’d be talking to my machine
all the time!

- Mr. T.

>
> 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.