Where to put supplementary docs?

[Mark Reinhold]

2025/4/24 11:26:50 -0400, Robbin Ehn <rehn at rivosinc.com>:
> Hi, I agree.
> 
> I suggested co-located docs in some less public forums in the past.
> 
> One major challenge with the other places (CR, JBS, PR, wiki), is that
> they don't handle versioning. (naturally) This means the code can't
> safely refer to, e.g., a wiki page, as that page may describe a newer
> version.  If a developer is working in JDK 11 or in the Loom project,
> they need the relevant documentation for that specific fork/branch.
> 
> JBS/PR also have the issue that they primarily describe the original
> bug/patch.  The code integrated can change significantly during the
> PR's lifetime, and one may need to read many comments in the PR/JBS to
> figure things out.
> 
> Additionally, many developers 'grep' the code, which means co-located
> documentation is very easy to find (and thus easier to keep up-to-date
> or add new docs to).
> 
> A concrete example: https://wiki.openjdk.org/display/HotSpot/Synchronization
> If you are hunting a bug in JDK 11, this page may be of value.
> If you want to know how locking works in JDK 25, you shouldn't be
> reading this page.
> 
> Co-locating the docs with the code helps with these issues.

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.

Jesper makes some good points, too, in his survey of the alternatives,
though I don’t agree with all of them.  Some commentary:

  - JBS doesn’t support markup in non-JEP/CSR issues, and we’re unlikely
    to change that. This makes it difficult to maintain longer documents
    there.  A nice side benefit of placing them in the repo is that we
    can use Markdown, and GitHub will render them.

  - JBS issues (and GitHub PRs) can be hard to discover.  To take
    Andrew’s example of the old HotSpot subtype-checking algorithm, if
    you wanted to know more about that then how would you find it in
    JBS?  Yet a quick search of `doc/ref/hotspot` would turn it up
    quickly.

  - Wikis are where information goes to die.  Sorry.  (Plus, the markup
    language is worse than horrid.)

  - Informational JEPs are under-used, but given that these documents
    are version-tied, informational JEPs are not a great solution.

  - The trouble with cr.openjdk.org, as Andrew pointed out, is that a
    document posted there today is not guaranteed to be there tomorrow,
    or next month, or next year.  People shuffle their personal content
    there all the time.

  - I totally agree that all OpenJDK-related documentation should be
    maintained and published in OpenJDK infrastructure.

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`.

- Mark