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

[Gabriel Scherer <gabriel.scherer@gmail.com>]

[-- Attachment #1: Type: text/plain, Size: 7582 bytes --]

On Mon, Mar 14, 2016 at 9:31 PM, Hendrik Boom <hendrik@topoi.pooq.com>
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 <ljs.darkfish@gmail.com> 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 <ljs.darkfish@gmail.com> 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 <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
> >>
> >>
> >
>

[-- Attachment #2: Type: text/html, Size: 9914 bytes --]