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

[Hendrik Boom <hendrik@topoi.pooq.com>]

On Mon, Mar 14, 2016 at 09:51:59AM -0400, 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.

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 <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
> >>
> >
> >
> 
> -- 
> 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