Call for Discussion: New Project: Developer's Guide -- suggestion to separate information having different life cycles

[Jesper Wilhelmsson]

> On 14 Mar 2020, at 02:34, Joe Darcy <joe.darcy at oracle.com> wrote:
> 
> Hello,
> 
> Having penned a complementary "OpenJDK Developers' Guide" back in 2010 [1], I wanted to offer a suggestion on structuring the new guide: separate information of different life cycles into different documents. For example, put any release-specific information into release-specific documents and put stable, mostly time-invariant information into the main developer's guide.

If you don't mind I think it would make sense to copy parts of that guide into the new developer's guide. Unless it's a document that you intend to keep around and maintain.

I agree that separating information based on life cycles is a good idea. Looking at the index of the old guide I don't think there is anything in there that is release specific. Some of my how-tos on the OpenJDK wiki do have release numbers in some examples but I think that can be re-worked as the processes themself are not release dependent.

> In the JDK code base, over the years we've recognized that hard-coded release values used in tests or the javadoc are often a maintenance burden. I think the same would be true of a developer's guide; the guide shouldn't necessarily need to be updated every six months (or three months) just because the feature releases have a six-month cadence and update releases come out every three months. [2]

I'm personally allergic to version numbers in version controlled documents. Especially these days when the document is online and most people have constant access to the latest version. The same goes for references to the JDK version in the text. If it can be made version agnostic (and most often it can) I think it should.

Thanks,
/Jesper

> 
> HTH,
> 
> -Joe
> 
> [1] http://cr.openjdk.java.net/~darcy/OpenJdkDevGuide/OpenJdkDevelopersGuide.v0.777.html
> 
> This material was used to seed the CSR compatibility discussion years later:
> 
> https://wiki.openjdk.java.net/display/csr/Kinds+of+Compatibility
> 
> [2] HT Prof. Edsger W. Dijkstra on describing the Buxton Index in his essay "The strengths of the academic enterprise" (https://www.cs.utexas.edu/users/EWD/transcriptions/EWD11xx/EWD1175.html). To rephrase the suggestion: avoid shear stress in the guide by not mixing content with different Buxton indexes.
>