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