Review Request: JDK-8180208 Provide a new docs bundle page

[Magnus Ihse Bursie]

On 2017-05-12 20:09, Mandy Chung wrote:
> Thanks Magnus for the review and feedback.
>
> Updated webrev:
>     http://cr.openjdk.java.net/~mchung/jdk9/webrevs/8180208/webrev.02
>
> - Merged with the recent changesets in jdk9/dev.
> - Renamed docs-jdk-index-html target to docs-jdk-index.
> - Keep the “Java SE” column header.  Add a new table header to separate the other modules.
> - I keep the API Specification there and improve this page as a follow-up issue.

Looks good to me!

>
> http://cr.openjdk.java.net/~mchung/jdk9/webrevs/8180208/docs/docs-index.html
>
>> On May 12, 2017, at 10:18 AM, Magnus Ihse Bursie <magnus.ihse.bursie at oracle.com> wrote:
>>> This is what I mentioned to coordinate with you.  You have a patch coming to stop building the technotes that I don’t know I should wait for your patch before changing it to index.html
>> I see. JDK-8175825 (Stop including pubs repo) is pushed now, so there should be no conflict with an index.html from there.
> Thanks.  I renamed it.
>
>> I don't think I made myself clear. On the page you are creating, the link for e.g. java.base goes to the module summary page for java.base, but the
>> The API link goes go api/index.html, which in turn links to e.g. the module summary page for java.base, while the but e.g. the "API specification" goes to the api/index.html page, which is just yet another collection of links to the module summary pages. It's like two different entry points to the collection of module summaries, one that is in alphabetic order and generated by javadoc, and one that's grouped per domain and generated by your tool.
>>
>> This is, in itself, not a problem. Both entry points can make perfect sense.
>>
> Yup and they give different views of the modules.  The API specification shows a complete list of the modules whereas this page gives a quick overview of some high level grouping.
>
>> What I'm trying to point out that this fact, that the "API specification" link is just another entry point to the same stuff that the table further down is linking to, is not made very clear. If you start with this page, you might very well come off with the impression that there's *two* sets of documentations, the "API specification" and the links to the different modules.
> I see the confusion you are pointing out.   I don’t have a good suggestion.

Maybe skip the three-bullet item list and rephrase it somewhat.

"The complete API specification is available from [this 
overview](api/index.html). The following table guides to to some 
important entry points".

Or something like that. I don't know. Should probably be done in a 
follow-up.

/Magnus

>
> Mandy
>