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.