Where to put supplementary docs?

[Mark Reinhold]

2025/4/28 12:19:09 -0400, jesper.wilhelmsson at oracle.com:
> This discussion seems to have taken a turn towards a different type of
> documentation than what I interpreted the initial question was
> about. When I read "supporting documents to justify a change", that's
> what I replied to. I still think these would be best off attached to
> the JBS issue. I would not like to see various spreadsheet files with
> benchmark data or images with graphs etc committed to the source code.

I agree that change-specific benchmark data would be inappropriate; it
ages too quickly.  Put that in JBS or in the PR (where, at least, it
will be rendered nicely).

> If we talk about descriptions of how the code is implemented,
> documentation for developers who need to understand subsystems in
> order to work on the code, then yes, I think it's totally reasonable
> to have that in markdown files in the source tree.
> 
> At least in my mind these are two different types of documents. Sorry
> if that's just me :-)

Nope.  It’s at least me and you.

Andrew -- Your initial message talked about “supporting documents to
justify a change,” which is broad and of concern.  The example you gave,
of the HotSpot subtype-checking algorithm, might have been created in
support of a specific change but it clearly falls into the narrower
category of “reference documentation for JDK internals.”  Are you
content with using that narrower category for this new documentation
directory?

- Mark