On Wed, 30 Jul 2025 18:53:40 GMT, Iris Clark <i...@openjdk.org> wrote:
>> This wording is what we came up with in internal discussion, but certainly >> open to suggestions. I created this PR to make the process more transparent. > > Minimally, I would not refer to the narrative specs which are part of the > platform as "Related documents" since that makes them sound weakly > advisory/informational. Perhaps something like "[Additional > specifications][../specs/index.html] for the Java language...". > > Also, if you're going to provide a link to the narrative specs, I'd also > consider adding a reference to the external spec page > (https://download.java.net/java/early_access/jdk25/docs/api/external-specs.html). The first word after “related documents” is “specify,” which doesn’t sound advisory to me. I don’t think the external spec page is of sufficiently broad interest to highlight it here. (To imply that our tool man pages are “specifications” is a bit much, but making that distinction isn’t worth the trouble here.) ------------- PR Review Comment: https://git.openjdk.org/jdk/pull/26547#discussion_r2243721464
