On Mon, Mar 14, 2016 at 8:30 AM, Gabriel Scherer <gabriel.scherer@gmail.com>
wrote:

> A nice quality of in-code comments that a video session does not have is
> locality: the explanations are closed to the explainees, so hopefully they
> can evolve in synch. Another nice quality (shared with blog posts) is that
> it can be proposed by third-parties and crowd-sourced with moderate
> efficiency: you can help document the OCaml implementation by sending a
> pull-request with comments on the parts you fought to understand.
>
> This has notably been done by Alain Frisch for the parsetree
> representation during the 4.01 development phase, and recently (4.03
> development cycle, GPR#310) in types.mli and typedtree.mli by Frédéric
> Bour, Gabriel Radanne and Thomas Refis, with helpful feedback from Alain
> Frisch and Jacques Garrigue.
>
> Anyone can help by submitting their own contribution to
> documentation-as-comments.
>
>
This is absolutely true, and I'm extremely grateful to all who commented --
the results are wonderful. The barriers to entry in this case, however, are
knowledge, quality and effort. By contrast, Jacques Garrigue (sorry for
picking on you Jacques) recording a session off the cuff on his laptop as
he casually steps through the code in his editor (he wouldn't even need a
webcam) and then uploading it to youtube would be a tremendous resource in
and of itself.

Another idea is that we develop a protocol for doing precisely this kind of
evolutionary crowdsourced commenting, but take the initial barrier out of
it.  Suppose that we allowed opening PRs on random files in the codebase. I
(or others) would ask questions about functions I didn't understand, and
other people would step up and explain them. Eventually, there might be
some documentation and clarification to add to the code. This would require
tolerance of 'unhelpful' and question-based documentation PRs. There might
be some very basic questions in there. We could add a specific tag, so
these PRs aren't closed prematurely (they could take a while). Would that
be ok?

-Yotam


> On Mon, Mar 14, 2016 at 11:36 AM, Goswin von Brederlow <goswin-v-b@web.de>
> wrote:
>
>> On Fri, Mar 11, 2016 at 12:04:17PM -0500, Yotam Barnoy wrote:
>> > While thinking about the best way to learn the new Flambda code in the
>> > minimal amount of time, I thought to myself, "wouldn't it be amazing to
>> > have Pierre Chambart and Mark Shinwell just do a video walkthrough of
>> their
>> > code". And then I thought about the rest of the codebase, about Jacques
>> > Garrigue doing a walkthrough of the typechecker code, and each expert(s)
>> > talking about the parts they know really well, and about how amazing it
>> > would be if we had this resource on youtube. It would be the ultimate
>> form
>> > of documentation by the foremost experts on aspects OCaml, welcoming
>> > programmers to contribute to the OCaml compiler in the easiest way
>> possible.
>> >
>> > A step further would be if this was done on Twitch or some similar live
>> > broadcasting platform, so people could actually ask live questions as
>> the
>> > session took place. The resulting video would be posted to youtube.
>> >
>> > What do you guys think?
>> >
>> > -Yotam
>>
>> I would watch that.
>>
>> MfG
>>         Goswin
>>
>> --
>> Caml-list mailing list.  Subscription management and archives:
>> https://sympa.inria.fr/sympa/arc/caml-list
>> Beginner's list: http://groups.yahoo.com/group/ocaml_beginners
>> Bug reports: http://caml.inria.fr/bin/caml-bugs
>>
>
>