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 9FB2F7F0AF for ; Mon, 14 Mar 2016 21:32:18 +0100 (CET) IronPort-PHdr: 9a23:84arPh93INMeAv9uRHKM819IXTAuvvDOBiVQ1KB91escTK2v8tzYMVDF4r011RmSDdqduqwP0raO+4nbGkU+or+5+EgYd5JNUxJXwe43pCcHRPC/NEvgMfTxZDY7FskRHHVs/nW8LFQHUJ2mPw6anHS+4HYoFwnlMkItf6KuStGU3pr8jrzqs7ToICx2xxOFKYtoKxu3qQiD/uI3uqBFbpgL9x3Sv3FTcP5Xz247bXianhL7+9vitMU7q3cYjck87NZNWrnWeKExTLoQTGh3cjN92Mq+vhDGSU6L52AAemQQiBtBRQbfvz/gWZKkkib8uvB822GwOsrzBeQ0VDKu9aZoYAPvkCAGcSY+93iRgct12vEI6Cm9rgByltaHKLqeM+BzK/+McA== Authentication-Results: mail2-smtp-roc.national.inria.fr; spf=None smtp.pra=hendrik@topoi.pooq.com; spf=None smtp.mailfrom=hendrik@topoi.pooq.com; spf=None smtp.helo=postmaster@april.topoi.pooq.com Received-SPF: None (mail2-smtp-roc.national.inria.fr: no sender authenticity information available from domain of hendrik@topoi.pooq.com) identity=pra; client-ip=69.165.131.134; receiver=mail2-smtp-roc.national.inria.fr; envelope-from="hendrik@topoi.pooq.com"; x-sender="hendrik@topoi.pooq.com"; x-conformance=sidf_compatible Received-SPF: None (mail2-smtp-roc.national.inria.fr: no sender authenticity information available from domain of hendrik@topoi.pooq.com) identity=mailfrom; client-ip=69.165.131.134; receiver=mail2-smtp-roc.national.inria.fr; envelope-from="hendrik@topoi.pooq.com"; x-sender="hendrik@topoi.pooq.com"; x-conformance=sidf_compatible Received-SPF: None (mail2-smtp-roc.national.inria.fr: no sender authenticity information available from domain of postmaster@april.topoi.pooq.com) identity=helo; client-ip=69.165.131.134; receiver=mail2-smtp-roc.national.inria.fr; envelope-from="hendrik@topoi.pooq.com"; x-sender="postmaster@april.topoi.pooq.com"; x-conformance=sidf_compatible X-IronPort-Anti-Spam-Filtered: true X-IronPort-Anti-Spam-Result: A0AiCwAfH+dW/4aDpUVdFoQCRwElqXmQS4FwIYI8gzACgWsTAQEBAQEBAQFjJ0ESAYFZghUBAQICDCYBOAMbCxgJBCEPBQ0LGSsJCYd9AxIOtz0DChWELwEBCAIBHYlcfoI9hSiBDwWFVkoMkR+FboVbQoFrCmSBTIxVhyqHUyEBQIQAIC4BhCKGQAEBAQ X-IPAS-Result: A0AiCwAfH+dW/4aDpUVdFoQCRwElqXmQS4FwIYI8gzACgWsTAQEBAQEBAQFjJ0ESAYFZghUBAQICDCYBOAMbCxgJBCEPBQ0LGSsJCYd9AxIOtz0DChWELwEBCAIBHYlcfoI9hSiBDwWFVkoMkR+FboVbQoFrCmSBTIxVhyqHUyEBQIQAIC4BhCKGQAEBAQ X-IronPort-AV: E=Sophos;i="5.24,337,1454972400"; d="scan'208";a="207730881" Received: from topoi.pooq.com (HELO april.topoi.pooq.com) ([69.165.131.134]) by mail2-smtp-roc.national.inria.fr with ESMTP; 14 Mar 2016 21:32:16 +0100 Received: by april.topoi.pooq.com (Postfix, from userid 1001) id E7C161A02FD; Mon, 14 Mar 2016 16:31:57 -0400 (EDT) Date: Mon, 14 Mar 2016 16:31:57 -0400 From: Hendrik Boom To: caml-list@inria.fr Message-ID: <20160314203157.GC2033@topoi.pooq.com> References: <20160314103608.GB21595@frosties> MIME-Version: 1.0 Content-Type: text/plain; charset=iso-8859-1 Content-Disposition: inline Content-Transfer-Encoding: 8bit In-Reply-To: User-Agent: Mutt/1.5.21 (2010-09-15) Subject: Re: [Caml-list] Flambda/compiler walkthrough + modularity On Mon, Mar 14, 2016 at 09:51:59AM -0400, Yotam Barnoy wrote: > 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. 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. Would such a recording bw useful to a documentatino writer? Possibly even one who writes comments to include in the code? As ever, may I suggest people look at the Trestle documentation at http://www.std.org/~msm/common/SRC-RR-068.pdf as an example of how good machine-generated documentation can be? Of course this takes care and attention whe writing the comments in the code. nd, presumably, a competent program to covert thsoe comments into a well-orgnnised volume. > > > > 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 PR? I donn't know the acronym. > (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 > >> > > > > > > -- > 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