Feedback on javadoc UI changes

Stuart Marks stuart.marks at oracle.com
Thu Oct 10 17:41:56 UTC 2019


One of the things I've always liked about javadoc is that it has the feel of a 
static web page. Of course, it was completely static initially. As time has gone 
on it's become more interactive, yet the static feeling is still there. I think 
this is a big advantage, because it gives me (the user) the feeling of absolute 
control, with nothing getting in my way. This is important when I'm looking for 
something, or concentrating on reading some bit of the specification. The 
smallest distraction is an impediment to this.

With this in mind, the animation of the top bar is anathema.

The problem here, as I see it, is that the animation of the top bar is 
independent of how fast or how much I've scrolled. With Version 2, for example, 
if I scroll down one line (one scroll wheel click), the top bar zips up and 
leaves a big swath of blank space. This is merely odd.

A different and bigger problem with Version 2 occurs when scrolling up in the 
middle of the page. Suppose I'm looking for methods in the Method Summary, which 
I know are in alphabetical order. I see that the method at the top of the window 
is just below the method I'm interested in, so I scroll the page up a few 
clicks. The top bar zips down and covers up what I'm looking at. I think that's 
a problem.

Let me suggest a variation of Version 3. Instead of the top bar animating up 
after you've scrolled down a few lines, the top bar should scroll up at exactly 
the same speed and distance as the main page, until the arrow/searchbox portion 
of the bar is pinned against the top. Since you can always pull it down 
explicitly, Version 3 lacks the zip-down misfeature I described above in Version 
2. However, when you get to the top of the page in Version 3, instead of 
animating down, the top bar should scroll back into view at the same rate as the 
user is scrolling the main page.

One issue I have with Version 3 is that the top bar animates down when I simply 
mouse over the down-arrow. To me, things ought to move when clicked. Since I'm 
expecting to click, I'm likely to click the thing that ends up underneath the 
pointer after the animation finishes, which is the Overview link. That'll take 
me away from what I was looking for, a big distraction.

Once pulled down explicitly, the top bar should either scroll away at the same 
rate as the page, or it should stick there until pushed up with an explicit 
action (e.g., clicking on an up-arrow, which might replace the down-arrow). I'm 
not sure which is preferable.

I know that I've seen techniques on the web that are similar to what I'm talking 
about. I'll see if I can find a good example.

s'marks

On 10/9/19 10:29 AM, Hannes Wallnöfer wrote:
> The javadoc team is considering changes to the UI of javadoc generated pages, specifically the behaviour of the top navigation bar and navigating to anchors within a page. Since this would affect all JDK users we thought it was a good idea to present/discuss the alternatives here on jdk-dev.
> 
> The feedback we are looking for:
> 
> - What do you prefer for scrolling up and down a page? Do you find the moving parts useful or distracting?
> - Which version is best for navigating to an anchor within a page (e.g. member search or internal links)?
> - Do you experience any technical problems with your particular browser?
> 
> Here are the three versions:
> 
> Version 1 is the conservative fix, it retains the fixed navigation bar, changes are mostly under the hood:
> 
> http://cr.openjdk.java.net/~hannesw/8223378/api.00/
> 
> Version 2: When scrolling down, the navigation bar slides upwards and disappears. When scrolling back up or starting to type for a search, it slides back in again.
> 
> http://cr.openjdk.java.net/~hannesw/8230852/api.04/
> 
> Version 3: Like version 2, but the part of the navigation bar that contains the search box and page-local links always remains visible. There’s an arrow symbol on the left to make the full navigation bar reappear.
> 
> http://cr.openjdk.java.net/~hannesw/8230852/api.03/
> 
> Hannes
> 


More information about the javadoc-dev mailing list