Re: [Caml-list] Flambda/compiler walkthrough + modularity

[Junsong Li <ljs.darkfish@gmail.com>]

May I ask whether we have module owners in the core team? That is, are
modules assigned to people in the core team? Generally I think it is a
bad idea, but if it is done so, owners can review the crowd-sourced
comments in their module.

Or, can people voluntarily review the crowd-sourced comments in
modules that they know well?

Thanks. We eventually get to the comments. When I read the ocamldoc
source, I had a few Aha moments, but I had no idea what to do about
them: maybe I should write it down somewhere, but as it is not close
to the source, it will be obsoleted anyway. Why bother?

On Mon, Mar 14, 2016 at 6:51 AM, Yotam Barnoy <yotambarnoy@gmail.com> wrote:
> 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
>>
>>
>