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

[Lyn Headley]

Thanks for the feedback all. There are many places this could go, but
I'll reply with one in particular to try and keep focus.

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

Two roles: elder and youth.

As part of using the editor, youth needs to occasionally make some
semantic gestures. She might also need to edit/annotate her own
history. But this could get cumbersome so we should limit it.

At all times, recording is either on or off, and youth can switch it
on or off. Whenever it is on, there is an active question (which youth
may give a description but which doesn't absolutely need one).
Recorded events append an event record to the active question. Youth
can delete, but not rearrange or insert events before posing the
active question (uploading it to the server where elders are listening
<-- note not "elder is").

I think these points address your comment above.

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

Youth is happy to receive feedback tomorrow because there is plenty to
think about and do in the meantime.


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

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

> *What* is easy to write?
> I think we need a lot more detail before it is possible to make
> that judgement.
>

Agreed.

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

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.

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. And this Q&A process can
become a kind of re-usable documentation over time.