Call for Discussion: New Project: Developer's Guide

[Martijn Verburg]

Hi John,

I totally get where you are coming from and the intent of message, all good!

Our group will be happy to help Jesper et al in *whatever capacity he and
the other experienced folks want us to*.

If that’s just reviewing drafts as newcomers or doing something like (dare
I say it boring) formatting work then we will roll up sleeves and do just
that ��.

Cheers,
Martijn



On Fri, 13 Mar 2020 at 08:34, John Rose <john.r.rose at oracle.com> wrote:

> 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

-- 
Cheers, Martijn (Sent from Gmail Mobile)