Call for Discussion: New Project: Developer's Guide

[John Rose]

On Mar 12, 2020, at 11:04 PM, Florian Weimer <fw at deneb.enyo.de> wrote:
> 
> * John Rose:
> 
>> And I suggest the same to others who are responding
>> with a “count me in”.  This project will require (as
>> Liam Neeson might say) “a very particular set of skills,
>> …acquired over a very long career.”  It is not a starter
>> task, as far as I can tell.  However, I’ll give deference to
>> Jesper, who might have a different vision for this.
> 
> Wouldn't input from people not completely familiar with the processes
> be valuable, so that it becomes clearer what needs documenting?

That’s a very good point.  Must that input be obtained by recruiting
such people as project members, or can it be acquired via other
means such as questionnaires and experience reports?

Also, to be honest:  I missed the import of Jesper’s
initial statement, “Strict rules for OpenJDK development
are… outside of the scope of this project.”  I think this
means that vexed questions like code reviews and style
guides are off the table for now, which means the analogy
of a hospital policy committee is not nearly as applicable
as I thought it was.  My apologies!

A new person’s experience is precious and should
be captured quickly, before it is forgotten.  My first
response to Martijn didn’t do justice to this fact.
We old-timers have no clue anymore what we know
and how we learned it the first time; “how to learn
it” is the whole job of a new person—but they forget
quickly once they learn the ropes.  Watching this
over and over again, I have noticed that we have no
good way to capture those new-person experiences.
(Long-haul experiences, on the other hand, are
abundantly documented.  The problem there is it
goes stale after a few years.)  I’d be really interested
to hear from people who have seen successful capture
of information from new folks to improve on-boarding.
My best take on it is to have a place where new folks
can share what they are learning *when the experience
is fresh*, in such a way that their more experienced
team mates can use it as raw material for the next
revision of the on-boarding guide.

I wish there were an OpenJDK wiki which would be
immediately open to all OpenJDK authors, exactly
for this purpose, but our infra isn’t set up that way.
Imagine reading the experience reports of the last
ten years of new folks, explaining what went right
and wrong, and commenting on each others’
experience…  The closest thing we have to this is
email archives, which are disorganized, and the
cr.ojn pages, which are isolated (and not intended
for documentation, though useful for it nevertheless).

Regarding the parts of the guide which would be for
long-haul use (not on-boarding), a big problem is
extracting the information from people who have been
working with the existing practices for long enough to
know their good sides and bad sides.   There’s always
the problem of keeping such documentation fresh.

Also, I think such a guide should be more descriptive
than prescriptive.  (Today in a different thread I
talked about descriptive vs. prescriptive, in the setting
of a proposal for a new prescriptive code style enforced
by robots.)  The current proposal to avoid “strict” rules
would seem to avoid the risks of prescriptiveness, for now.

Is there a difference between “long haul” and “on-boarding”
documentation?  Yes, because they are for different audiences.
Every project demands that the new folks learn a bunch of
stuff before they do anything; hopefully it’s not too much
and it’s easy to learn, and then your apprenticeship begins.
Also, every project has a much larger set of best practices
and specifications which don’t need to be learned up front,
but which still shape the project as a whole.  No one person
knows them all at once, but people need to refer to them.
I’m talking about documentation like “how to do gatekeeping”
or “what are the bytecodes of the JVM”.  I would think
those would go into a dev-guide of some sort, but in a
different place than the important “how to get started”
sections.

I hope Jesper will have more comments on these puzzles.

— John