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 1F4007F0AF for ; Mon, 14 Mar 2016 14:52:21 +0100 (CET) IronPort-PHdr: 9a23:nuuCMxdGyASVv6rwWkVCx8d3lGMj4u6mDksu8pMizoh2WeGdxc+6YB7h7PlgxGXEQZ/co6odzbGG7OaxByddud6oizMrTt9lb1c9k8IYnggtUoauKHbQC7rUVRE8B9lIT1R//nu2YgB/Ecf6YEDO8DXptWZBUiv2OQc9HOnpAIma153xjLDtvcyNKFgQzBOGIppMbzyO5T3LsccXhYYwYo0Q8TDu5kVyRuJN2GlzLkiSlRuvru25/Zpk7jgC86l5r50IeezAcq85Vb1VCig9eyBwvZWz9Er1dhaU/nYXTkkRlxNJBUCFsEC7Dd/NtX7Vv+Bn2SSedfb9Tb0uVC7qu6hiQgXphSNBLDU5/XvakOR/iatapFSqoBkpkKDOZ4TABf1id6aVV9oAQ21QFpJAUDBIB4m1dY0IHsIOOO9Zq8/2oF5Y/kj2PhWlGO66kmwAvXTxx6Bvlrl4HA== Authentication-Results: mail2-smtp-roc.national.inria.fr; spf=None smtp.pra=yotambarnoy@gmail.com; spf=Pass smtp.mailfrom=yotambarnoy@gmail.com; spf=None smtp.helo=postmaster@mail-yw0-f169.google.com Received-SPF: None (mail2-smtp-roc.national.inria.fr: no sender authenticity information available from domain of yotambarnoy@gmail.com) identity=pra; client-ip=209.85.161.169; receiver=mail2-smtp-roc.national.inria.fr; envelope-from="yotambarnoy@gmail.com"; x-sender="yotambarnoy@gmail.com"; x-conformance=sidf_compatible Received-SPF: Pass (mail2-smtp-roc.national.inria.fr: domain of yotambarnoy@gmail.com designates 209.85.161.169 as permitted sender) identity=mailfrom; client-ip=209.85.161.169; receiver=mail2-smtp-roc.national.inria.fr; envelope-from="yotambarnoy@gmail.com"; x-sender="yotambarnoy@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-yw0-f169.google.com) identity=helo; client-ip=209.85.161.169; receiver=mail2-smtp-roc.national.inria.fr; envelope-from="yotambarnoy@gmail.com"; x-sender="postmaster@mail-yw0-f169.google.com"; x-conformance=sidf_compatible X-IronPort-Anti-Spam-Filtered: true X-IronPort-Anti-Spam-Result: A0CQBgDpwOZWdqmhVdFdhBhtBoJvpwOQS4FwIYVsAoEmBzoSAQEBAQEBAQEQAQoLCwkcBS+CLYIUAQEBAwEMBhEdARsPAwsBAwELBgMCCw0NHQICIQEBEQEFAQoSBhMSEIdsAQMKCA6PCI9BgTE+MYs2gWqCV4UwChknAwoVPINzAQEBAQYBAQEBARUBBQoFhgmDRH6CPYIqglOBOgWGIAyMV4RIhW6GHYF1gjCMVYcqhhURHoEPDxgMgiWCCiAuimMBAQE X-IPAS-Result: A0CQBgDpwOZWdqmhVdFdhBhtBoJvpwOQS4FwIYVsAoEmBzoSAQEBAQEBAQEQAQoLCwkcBS+CLYIUAQEBAwEMBhEdARsPAwsBAwELBgMCCw0NHQICIQEBEQEFAQoSBhMSEIdsAQMKCA6PCI9BgTE+MYs2gWqCV4UwChknAwoVPINzAQEBAQYBAQEBARUBBQoFhgmDRH6CPYIqglOBOgWGIAyMV4RIhW6GHYF1gjCMVYcqhhURHoEPDxgMgiWCCiAuimMBAQE X-IronPort-AV: E=Sophos;i="5.24,335,1454972400"; d="scan'208,217";a="207662822" Received: from mail-yw0-f169.google.com ([209.85.161.169]) by mail2-smtp-roc.national.inria.fr with ESMTP/TLS/AES128-GCM-SHA256; 14 Mar 2016 14:52:19 +0100 Received: by mail-yw0-f169.google.com with SMTP id g3so167388368ywa.3 for ; Mon, 14 Mar 2016 06:52:19 -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=wfObhbJ9QUDx9mjDJVL+pi/tqmzKXC+zXCJ2MU+FI7o=; b=WNAcASSt0iRN/tKCAJYbJj+5+z+6Cgh5FElIwGN+gGCZwBQQjMAbl8r0XQyTbiTN4M mhNTmdLKTRX6pDQ6DMSDz1QotCOnnUnvbjsKCaYv/MmF2TuQtSUdA577/48Tf+aQvjHk 1sWialaA4B4CWXbRVa08AJBiJMX9di9rrqtVNmb8QDz6/UNmYgdiSshmn5k/vQIAVk55 04lQVCoKKmBbF76nHgOIKYxqH4kG2SdNaQKSqJ9swqrzF78FPswp/7kSw27MVAa5H3qO Vr7rXwYeDPQ5+XKs5gmmOgQZoox7M2HBU+j3tsM3ggWWDGpHPt8HUXMvwTHLAEjjkeWv nD9A== 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=wfObhbJ9QUDx9mjDJVL+pi/tqmzKXC+zXCJ2MU+FI7o=; b=l1mVGxMk2KzT2JSmFeOCnmA5kTWWvg70Ioh4SMhk5uYoMik9K0So+7exRnsPO2Ke2T 4UFVbxxvncFn5iTjxoK2a678Yv+Iu3osTn47/TWP64asjyXTklWwnGFDpeptvWun+dQR plhf5oHBJKZ3WhVTIVV+j73cougthZ7F07Ag/lJKiPmZ5wfS1eFahrDZ4Tv59PNzCE5O 39QfITYlXpwJHEQzw0+tRSCG/6tirx4uUQLXs9k53DKHdIeqPPNKIPeTfIAhoQ1DTUSA EnLFJwydHMcK33UkOyXA8YRIm1XL8Emk+9pBtsf9eo1gdU3GQ9U/rI4EmF6VvacGXvXA Golg== X-Gm-Message-State: AD7BkJJpl06SMZMGrlN5DUW1rKFpzmZjmsa/zX/cf1YhtTeAoKRYf7vlI+ulPego+flpGvM1F/NyVgE9WRJRug== X-Received: by 10.129.98.5 with SMTP id w5mr13521821ywb.4.1457963538560; Mon, 14 Mar 2016 06:52:18 -0700 (PDT) MIME-Version: 1.0 Received: by 10.37.13.3 with HTTP; Mon, 14 Mar 2016 06:51:59 -0700 (PDT) In-Reply-To: References: <20160314103608.GB21595@frosties> From: Yotam Barnoy Date: Mon, 14 Mar 2016 09:51:59 -0400 Message-ID: To: Gabriel Scherer Cc: Goswin von Brederlow , Ocaml Mailing List Content-Type: multipart/alternative; boundary=001a11473282cfbf24052e029646 Subject: Re: [Caml-list] Flambda/compiler walkthrough + modularity --001a11473282cfbf24052e029646 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: quoted-printable On Mon, Mar 14, 2016 at 8:30 AM, Gabriel Scherer 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=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 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 > 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 >> > > --001a11473282cfbf24052e029646 Content-Type: text/html; charset=UTF-8 Content-Transfer-Encoding: quoted-printable
On M= on, Mar 14, 2016 at 8:30 AM, Gabriel Scherer <gabriel.scherer@gma= il.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 th= ey can evolve in synch. Another nice quality (shared with blog posts) is th= at it can be proposed by third-parties and crowd-sourced with moderate effi= ciency: you can help document the OCaml implementation by sending a pull-re= quest with comments on the parts you fought to understand.

This has = notably been done by Alain Frisch for the parsetree representation during t= he 4.01 development phase, and recently (4.03 development cycle, GPR#310) i= n types.mli and typedtree.mli by Fr=C3=A9d=C3=A9ric Bour, Gabriel Radanne a= nd Thomas Refis, with helpful feedback from Alain Frisch and Jacques Garrig= ue.

Anyone can help by submitting their own contribution to document= ation-as-comments.


This is absolutely true, and I'm extremely grate= ful to all who commented -- the results are wonderful. The barriers to entr= y in this case, however, are knowledge, quality and effort. By contrast, Ja= cques Garrigue (sorry for picking on you Jacques) recording a session off t= he 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 evolut= ionary crowdsourced commenting, but take the initial barrier out of it.=C2= =A0 Suppose that we allowed opening PRs on random files in the codebase. I = (or others) would ask questions about functions I didn't understand, an= d other people would step up and explain them. Eventually, there might be s= ome documentation and clarification to add to the code. This would require = tolerance of 'unhelpful' and question-based documentation PRs. Ther= e 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). Woul= d that be ok?

-Yotam
=C2=A0
On Mon, Mar 14, 2016 at 11:36 AM= , Goswin von Brederlow <goswin-v-b@web.de> wrote:
<= /div>
On Fri, Ma= r 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 J= acques
> Garrigue doing a walkthrough of the typechecker code, and each expert(= s)
> talking about the parts they know really well, and about how amazing i= t
> 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 pos= sible.
>
> A step further would be if this was done on Twitch or some similar liv= e
> 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
=C2=A0 =C2=A0 =C2=A0 =C2=A0 Goswin

--
Caml-list mailing list.=C2=A0 Subscription management and archives:
https://sympa.inria.fr/sympa/arc/caml-list
Beginner's list: http://groups.yahoo.com/group/ocam= l_beginners
Bug reports: http://caml.inria.fr/bin/caml-bugs


--001a11473282cfbf24052e029646--