Uploaded image for project: 'JDK'
  1. JDK
  2. JDK-8320458

Improve structural navigation in API documentation

XMLWordPrintable

    • b07
    • generic
    • generic

      Structural navigation in JavaDoc-generated API documentation has not seen significant improvements in many years, in fact the basic concepts and layout go back to the early days of Java. There are several areas where structural navigation could be improved:

       - Main (global) navigation consists of a horizontal navigation bar that provides links to top-level pages as well as the three levels of documented API elements: module, package, class. There are two main problems with this setup:

            - Module, package and class are displayed as plain text labels if no element suitable element is available in the context of the page. This means that for top-level pages all three are displayed as plain labels. What makes this problematic is that the current style makes it impossible to distinguish links from labels. But even with that solved, the concept of displaying "disabled" links to keep the content of the main navigation consistent should maybe be reconsidered. (The same applies for the "Use" pages which are only available in package and class pages.)

           - Module, package and class links are labeled "MODULE", "PACKAGE" and "CLASS" and do not show the actual names of these program elements, which of course is due to their inclusion in the main navigation. This squanders the potential of using these links to provide additional contextual guidance that a "breadcrumb" style navigation with element-named labels could provide.

       - Local (page level) navigation is provided by a horizontal sub-navigation beneath the main navigation bar which provides anchor links to sections within the page, which depend on page type.

          - Like in the main navigation, unavailable links are displayed as plain text labels, which works a bit better here since labels can actually be distinguished from links, but the distinction is not very obvious and I would question the benefit of structural uniformity towards recognizing which sections are available on a particular page. (As a case in point, each Java interface page has CONSTR labels for constructor summary and details.)

          - For class-level pages (which tend to be quite large) this mechanism of local navigation seems inadequate, as one has to navigate to the specific member summary and find the member in the summary table which can still be quite extensive and confusing).

      The following changes would help to improve global and local navigation in JavaDoc-generated documentation:

       - Move module/package/class-level navigation out of the main navigation into a dedicated breadcrumbs-style navigation.
       - Provide a table of contents where it makes sense. This should include links to top-level headings in documentation text and for class-level pages links to the members of the class.
       - Use responsive design to adapt the layout of navigation to the available screen space. On large displays, the table of contents should be displayed in a sidebar. On small displays, the table of contents should be integrated into the collapsible menu.
       - Moving local navigation links from the subnavigation bar into a sidebar will free up the subnavigation bar for the dedicated breadcrumbs navigation.

            hannesw Hannes Wallnoefer
            hannesw Hannes Wallnoefer
            Votes:
            0 Vote for this issue
            Watchers:
            3 Start watching this issue

              Created:
              Updated:
              Resolved: