Where to put supplementary docs?

[Magnus Ihse Bursie]

On 2025-04-25 21:41, Mark Reinhold wrote:

> My initial internal reaction to Andrew’s proposal was, “meh, yet another
> place to search for documents?”  But Robbin makes a good point: If what
> we’re talking about here is documentation of JDK internals then that’s
> inherently version-specific.  Keeping such documentation anywhere else
> just invites it to get stale and out of date, in addition to making it
> harder to find.
>
> If we do go ahead with Andrew’s proposal then it will be critical to
> crisply define what this directory for, lest it become a dumping ground
> for documents that really belong elsewhere, or mistaken for a collection
> of documents meant for non-contributors.
>
> “Reference documentation for JDK internals” seems like a good start,
> which also suggests that `doc/internals` might be a better name than
> `doc/ref`.

I like "doc/internals". I think it captures well what we are discussing 
here.

I don't think we need to overthink this. Is there anything stopping 
anyone from starting to use this straight away? Any kind of additional 
structures/guidelines etc can be added later on, if this turns out to be 
so well-used it gets overcrowded.

Maybe someone can volunteer to scour other places for existing 
documentation that is still relevant, and add it to doc/internals, to 
get a good starting point.

/Magnus

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://mail.openjdk.org/pipermail/jdk-dev/attachments/20250428/38bd435b/attachment.htm>