Call for Discussion: New Project: Developer's Guide

[Jesper Wilhelmsson]

> On 14 Mar 2020, at 01:21, John Rose <john.r.rose at oracle.com> wrote:
> 
> On Mar 13, 2020, at 6:29 AM, Jesper Wilhelmsson <jesper.wilhelmsson at oracle.com <mailto:jesper.wilhelmsson at oracle.com>> wrote:
>> 
>> The question right now I think is more of the kind; Do we think it would be useful to have an up-to-date developer's guide, and do we think an OpenJDK project is the right way to do that work?
> 
> Yes, please.  Thanks for taking this on.  Please see my previous
> comments; maybe they are helpful.  I’m particularly passionate
> about our poor information capture from the experiences of
> new people, and I think this project might consider making
> that better somehow, on the grounds that the dev-guide can
> a living document, if it can keep its information fresh, and
> otherwise will have a short career.
> 
> Capturing thoughtful experience reports from new folks
> would seem to be the raw material of a healthy dev-guide,
> specifically the on-boarding part.  The long-haul part
> has similar care-and-feeding requirements, but those
> should be satisfied by bug/rfe reports from the group
> as a whole.

I'm absolutely pro capturing comments and experiences from new people, and I think that as the guide is updated and people see that it is a living document suggestions for improvements will start dropping in automatically. If we need some extra action to capture new peoples experiences from the guide, let's do that, but to be honest I don't think it will be necessary as long as the guide is a living document. If I read a document and find some small issue in the text I'm a lot more motivated to file a report if I see that the document has been updated recently and the issue I found was the only bug in there, compared to if the document hasn't been updated since 2012 and is completely out of date.

We could always encourage feedback by a note of the first page like:

"We hope that you will enjoy this guide and find it helpful. If you find anything that seems odd, or something that is not clearly explained, please let us know by sending an email to guide-dev at openjdk.java.net. Thank you for your feedback!   And by the way, here's the guide for how to join the OpenJDK mail lists: ..."

Cheers,
/Jesper