From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: X-Original-To: caml-list@sympa.inria.fr Delivered-To: caml-list@sympa.inria.fr Received: from mail2-relais-roc.national.inria.fr (mail2-relais-roc.national.inria.fr [192.134.164.83]) by sympa.inria.fr (Postfix) with ESMTPS id 6119F7F0AF for ; Tue, 15 Mar 2016 02:03:35 +0100 (CET) IronPort-PHdr: 9a23:XtdxGBP+nYtVOjaQ9Wkl6mtUPXoX/o7sNwtQ0KIMzox0Kfz4rarrMEGX3/hxlliBBdydsKIbzbuJ+Pq8EUU7or+/81k6OKRWUBEEjchE1ycBO+WiTXPBEfjxciYhF95DXlI2t1uyMExSBdqsLwaK+i760zceF13FOBZvIaytQ8iJ35vxhr/5ocGbSj4LrQT+SIs6FA+xowTVu5teqqpZAYF19CH0pGBVcf9d32JiKAHbtR/94sCt4MwrqHwI6LoJvvRNWqTifqk+UacQTHF/azh0t/vQqALbQACTynwZW2QQ2loUUkmWpC39C7XstDD9sOU1/CjSacn0VvY4UC6h4aZwSDfnjS4GM3gy92SB2eJqi6cOjxurvR1yx8bva4GYLvdkNvfSdNkARGdFGN1aVyFbD5mUYI4GDu5HNuFd+dqu72ASpAezUFH/TNjkzSVF0zqrhKA= Authentication-Results: mail2-smtp-roc.national.inria.fr; spf=None smtp.pra=gabriel.scherer@gmail.com; spf=Pass smtp.mailfrom=gabriel.scherer@gmail.com; spf=None smtp.helo=postmaster@mail-io0-f176.google.com Received-SPF: None (mail2-smtp-roc.national.inria.fr: no sender authenticity information available from domain of gabriel.scherer@gmail.com) identity=pra; client-ip=209.85.223.176; receiver=mail2-smtp-roc.national.inria.fr; envelope-from="gabriel.scherer@gmail.com"; x-sender="gabriel.scherer@gmail.com"; x-conformance=sidf_compatible Received-SPF: Pass (mail2-smtp-roc.national.inria.fr: domain of gabriel.scherer@gmail.com designates 209.85.223.176 as permitted sender) identity=mailfrom; client-ip=209.85.223.176; receiver=mail2-smtp-roc.national.inria.fr; envelope-from="gabriel.scherer@gmail.com"; x-sender="gabriel.scherer@gmail.com"; x-conformance=sidf_compatible; x-record-type="v=spf1" Received-SPF: None (mail2-smtp-roc.national.inria.fr: no sender authenticity information available from domain of postmaster@mail-io0-f176.google.com) identity=helo; client-ip=209.85.223.176; receiver=mail2-smtp-roc.national.inria.fr; envelope-from="gabriel.scherer@gmail.com"; x-sender="postmaster@mail-io0-f176.google.com"; x-conformance=sidf_compatible X-IronPort-Anti-Spam-Filtered: true X-IronPort-Anti-Spam-Result: A0DCAADTXudWkrDfVdFdhBhtBoJvpwaQPQENgXAhgjyDMAKBLAc4FAEBAQEBAQEBEAEBAQEHCwsJIS+CLYIUAQEBAwEMBhEEGQEbDwMLAQMBCwYDAgsDCg0dAgIhAQERAQUBChIGExIQh20BAwoIDo9Ej0GBMT4xizaBaoJXhV0KGScDChU8g3MBAQgBAQEBARUBBQoFhgmDRH6CPYIqglOBOgWGIAyRH4FPhB+GHYF1gWVLhySFMYcrhhURHoEPDw8BAYI4DREIgUo7LopjAQEB X-IPAS-Result: A0DCAADTXudWkrDfVdFdhBhtBoJvpwaQPQENgXAhgjyDMAKBLAc4FAEBAQEBAQEBEAEBAQEHCwsJIS+CLYIUAQEBAwEMBhEEGQEbDwMLAQMBCwYDAgsDCg0dAgIhAQERAQUBChIGExIQh20BAwoIDo9Ej0GBMT4xizaBaoJXhV0KGScDChU8g3MBAQgBAQEBARUBBQoFhgmDRH6CPYIqglOBOgWGIAyRH4FPhB+GHYF1gWVLhySFMYcrhhURHoEPDw8BAYI4DREIgUo7LopjAQEB X-IronPort-AV: E=Sophos;i="5.24,337,1454972400"; d="scan'208,217";a="207754472" Received: from mail-io0-f176.google.com ([209.85.223.176]) by mail2-smtp-roc.national.inria.fr with ESMTP/TLS/AES128-GCM-SHA256; 15 Mar 2016 02:03:33 +0100 Received: by mail-io0-f176.google.com with SMTP id g203so6066592iof.2 for ; Mon, 14 Mar 2016 18:03:33 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20120113; h=mime-version:in-reply-to:references:from:date:message-id:subject:to :cc; bh=JdslbT3eN2Aa/Q2pOyL95ttp1PbOkiSvxzV59th4dVg=; b=xOcNg1umUO6jLfxYfnSU1sffOj9sq22+hF71URItQ/lhLIH5x8J2l38nl4L5CyHGdR XNUojlRzEXLnZTFZ6Twx4WivZRj5GhAnA7tnk7Q+0rVRWJt6+isUCT+2talT1v1vHpiR XdDs3vCUbz6Dm2niUguimTbQEH6yTSbE1f2/KS0TWJk1F7q65oG7BTbe2wO5eynknS28 D2ygbwaQHNmF/nRX/9dNJTDr4GPkDSn8MRM3pFfVWX/AsD/UqkU1ViulD9MZRbYWMnS6 vWASXalgr83Ox3RPrMUL99/UWjl1D2oeyY0Qsg1oFOkk8bKHjHD7PSIAKZPZMaSLEpgs i3xA== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20130820; h=x-gm-message-state:mime-version:in-reply-to:references:from:date :message-id:subject:to:cc; bh=JdslbT3eN2Aa/Q2pOyL95ttp1PbOkiSvxzV59th4dVg=; b=Aw+RVEflOTGOZDs3e6mA+L43t+TdAGQVwaIPuzzeMIq3fe/chAq9IYzQOhx35Ga393 /ESx3YxaNO5zqCR/gv1H9TCtE7h3TvSeeK1KBJXUB6pN2oT/nhMCip9i768R+OErf4tY Wqqs6GPKPiNc6yYv3B5fTgex9xsEWX/eyjgiB5VyLo1o+/kGOjgypsDnhFr4nSCiAuH0 kuLotJ1lqjqDxqJrw9GFh7Evl7KM5eVpbl8T5SumeGGp9E5AbR89Kf4B2rCDThL3TbTY qy40Yp2KLnbaVIB+uUCHNTiV3GPLETPLFnl61C1DIvcKkpGLD7z2yKKte/TodVo35Z6k kfXg== X-Gm-Message-State: AD7BkJKUyvHswXy+pvPFnGL6GOwuLdH7y9tfuINFBex9oipLwd2W/Q1uyzlouUlsxVQ+CilP3K0wQ69mC+cMBw== X-Received: by 10.107.47.163 with SMTP id v35mr25173296iov.19.1458003812367; Mon, 14 Mar 2016 18:03:32 -0700 (PDT) MIME-Version: 1.0 Received: by 10.79.17.4 with HTTP; Mon, 14 Mar 2016 18:02:52 -0700 (PDT) In-Reply-To: References: <20160314103608.GB21595@frosties> From: Gabriel Scherer Date: Tue, 15 Mar 2016 02:02:52 +0100 Message-ID: To: Junsong Li Cc: Yotam Barnoy , Goswin von Brederlow , Ocaml Mailing List Content-Type: multipart/alternative; boundary=001a11c151ce5161ff052e0bf73a Subject: Re: [Caml-list] Flambda/compiler walkthrough + modularity --001a11c151ce5161ff052e0bf73a Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: quoted-printable On Mon, Mar 14, 2016 at 9:31 PM, Hendrik Boom wrote: > The main problem a technical writer faces in documenting someone > else's software is to understand it. Without that, he might produce > elegant documentation that looks good but is utterly useless. > This is true, but note that this problem also happens when people contribute code changes to the project. They start by constructing a local understanding of what is happening, then use this knowledge to write a patch. The patch may be a documentation patch, or a fix or a new feature, and there is a risk in all cases. Currently people rather send code changes only, so it's good to remind that they can also document their assumption in passing (or just send documentation patches); a review will be needed anyway. I'm not assuming a separation of role between "development" and "documentation" in my remark above. I never had the luck of working with technical authors dedicated mostly to writing documentation, so I cannot comment on how people with such a profile would best contribute -- but they should definitely get in touch to sort it out. (Sorry about the acronym-speak. PR is actually a loaded acronym for the OCaml project right now, as it may denote either a "Pull Request" on the github interface for code contributions, or a "Problem Report" on the Mantis bugtracker. One can be explicit and say GPR and MPR. It is also possible to send patches on the bugtracker, so here I should just have said "patches".) On Mon, Mar 14, 2016 at 10:05 PM, Junsong Li wrote: > 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. > Some regions of the codebase have a well-defined maintainer (typing -> Jacques Garrigue, pattern-matching -> Luc Maranget, backend -> Xavier Leroy, garbage collector -> Damien Doligez), and some people are experts on more local or cross-cutting aspects. As far as I know, there is no formal ownership structure, but people triaging bugs or change proposals will usually know who to ask before making decisions. You don't need to know in advance who would be the best reviewer to send a patch. > Or, can people voluntarily review the crowd-sourced comments in modules > that they know well? > Yes, and this is encouraged. More generally, people should feel free to look at the bugreports and try to propose a fix (whether they "know well" the affected part of the codebase or not), and to look at the proposed patches and review them -- which means commenting on everything that feel strange or that you do not understand in the patch. On Mon, Mar 14, 2016 at 10:05 PM, Junsong Li wrote: > 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 > 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=C3=A9= d=C3=A9ric > 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 ultima= te > >>> > 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 > >> > >> > > > --001a11c151ce5161ff052e0bf73a Content-Type: text/html; charset=UTF-8 Content-Transfer-Encoding: quoted-printable
On Mon, Mar 14, 2016 at 9:31 PM, Hendrik Boom <hendr= ik@topoi.pooq.com> wrote:
The main problem a technical writer faces in documenting = someone
else's software is to understand it.=C2=A0 Without that, he might produ= ce
elegant documentation that looks good but is utterly useless.

This is true, but note that this problem also happens when people contribute code changes to the project. They start by constructing a local=20 understanding of what is happening, then use this knowledge to write a=20 patch. The patch may be a documentation patch, or a fix or a new=20 feature, and there is a risk in all cases. Currently people rather send=20 code changes only, so it's good to remind that they can also document=20 their assumption in passing (or just send documentation patches); a=20 review will be needed anyway.

I'm not assuming a=20 separation of role between "development" and "documentation&= quot; in my=20 remark above. I never had the luck of working with technical authors=20 dedicated mostly to writing documentation, so I cannot comment on how=20 people with such a profile would best contribute -- but they should definit= ely get in touch to sort it out.

(Sorry about the acronym-speak. PR is actually a loaded acronym for the OCaml=20 project right now, as it may denote either a "Pull Request" on th= e=20 github interface for code contributions, or a "Problem Report" on= the=20 Mantis bugtracker. One can be explicit and say GPR and MPR. It is also=20 possible to send patches on the bugtracker, so here I should just have=20 said "patches".)

On Mon, Mar 14, 2016 at 10:05 PM, J= unsong Li <ljs.darkfish@gmail.com> wrote:
May I ask whether we have module ow= ners 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.

Some regions of the codebase have a well-defined maintainer (typing -> Jacques=20 Garrigue, pattern-matching -> Luc Maranget, backend -> Xavier=20 Leroy, garbage collector -> Damien Doligez), and some people are=20 experts on more local or cross-cutting aspects. As far as I know, there is = no formal ownership structure, but people triaging bugs or change proposals w= ill=20 usually know who to ask before making decisions. You don't need to know= =20 in advance who would be the best reviewer to send a patch.
= =C2=A0
Or, can people voluntarily review the crowd-sourced comments in modules tha= t they know well?

Yes,=20 and this is encouraged. More generally, people should feel free to look=20 at the bugreports and try to propose a fix (whether they "know well&qu= ot; the affected part of the codebase or not), and to look at the proposed=20 patches and review them -- which means commenting on everything that=20 feel strange or that you do not understand in the patch.

On Mon, Mar 14, 2016 at 10= :05 PM, Junsong Li <ljs.darkfish@gmail.com> wrote:
<= blockquote class=3D"gmail_quote" style=3D"margin:0 0 0 .8ex;border-left:1px= #ccc solid;padding-left:1ex">May I ask whether we have module owners in th= e 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 h= ave is
>> locality: the explanations are closed to the explainees, so hopefu= lly 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 moderat= e
>> efficiency: you can help document the OCaml implementation by send= ing a
>> pull-request with comments on the parts you fought to understand.<= br> >>
>> 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= =C3=A9d=C3=A9ric 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 com= mented --
> the results are wonderful. The barriers to entry in this case, however= , are
> knowledge, quality and effort. By contrast, Jacques Garrigue (sorry fo= r
> 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 ne= ed a
> webcam) and then uploading it to youtube would be a tremendous resourc= e in
> and of itself.
>
> Another idea is that we develop a protocol for doing precisely this ki= nd of
> evolutionary crowdsourced commenting, but take the initial barrier out= of
> it.=C2=A0 Suppose that we allowed opening PRs on random files in the c= odebase. I
> (or others) would ask questions about functions I didn't understan= d, and
> other people would step up and explain them. Eventually, there might b= e 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 tha= t 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:<= br> >>> > While thinking about the best way to learn the new Flambd= a 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 wa= lkthrough of
>>> > their
>>> > code". And then I thought about the rest of the code= base, 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 ea= siest way
>>> > possible.
>>> >
>>> > A step further would be if this was done on Twitch or som= e similar live
>>> > broadcasting platform, so people could actually ask live = questions as
>>> > the
>>> > session took place. The resulting video would be posted t= o youtube.
>>> >
>>> > What do you guys think?
>>> >
>>> > -Yotam
>>>
>>> I would watch that.
>>>
>>> MfG
>>>=C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0Goswin
>>>
>>> --
>>> Caml-list mailing list.=C2=A0 Subscription management and arch= ives:
>>> https://sympa.inria.fr/sympa/arc/caml-list
>>> Beginner's list: http://groups.yahoo.c= om/group/ocaml_beginners
>>> Bug reports: http://caml.inria.fr/bin/caml-bugs >>
>>
>

--001a11c151ce5161ff052e0bf73a--