New documentation layout


(Dimitar Dimitrov) #1

First to say I really like the new layout that I can see at the nightly docs.

Here is a bit of feedback which I hope may be useful:

  • the new layout has the diagrams scaled down to useless dimensions. See the task dependency graph at the Java plugin - completely unreadable.
  • forcing the content to a narrow column is counter-productive - if I need to, I can easily use my window manager to get the page to my preferred reading width.
  • related to the previous point, some basic Javascript for varying the font-size and margins would be very useful (for me, I would set it to large font and no margins)
  • consider listing the second-level headings in the right sidebar (i.e. for chapters like ‘Advanced dependency management’)
  • a good print stylesheet would be very appreciated - I often do “print selection” - good printing fonts, margins, colors and spacing make a difference. I may actually contribute one if you are open to it.

(Sterling Greene) #2

Ping @eriwen who’s been leading the charge on these improvements.

One thing I noticed on the page you linked to, the tables are cut off too:


(Chris Doré) #3

I’d like to strongly second that opinion.


(Eric Wendelin) #4

Thanks for the feedback @ddimitrov and @Chris_Dore.

There’s a decent amount of cleanup to be done to be ready for Gradle 4.5, and I’ll add your points to the list.

Regarding the narrower content area, would it be sufficient to allow the navigation on the right to be collapsed and expand the content area to fill the space? Folks tend to find it difficult to follow long lines, so I hesitate to default to a wide layout. Do you have other ideas here?


(Chris Doré) #5

I would generally just prefer that the text area be made wider. No need to add to our click counts when there’s a large of amount of whitespace on most developer’s widescreen displays (are any of us still using 4:3 displays these days? :slight_smile: ).

It doesn’t have to be full width, but it would sure help make certain things, like some tables, easier to read. Tables that are wrapped too much make them long, to the point where they need to be scrolled, and scrolling with tables can be frustrating when you’re new to the table contents and have to reference column headers.


(Eric Wendelin) #6

Got it. I’m spiking an alternate layout and discussing with our designer how to widen the content area.

Thanks again for the feedback!


(Dimitar Dimitrov) #7

Instead of collapsing the sidebars (which I find useful), how about providing a simple style switching UI so one can pick their preferred margins?

This is how the Kindle Online does it (probably a bit of overkill for a docs site :slight_smile: )


(Eric Wendelin) #8

@ddimitrov @Chris_Dore I’ve just deployed a nightly that expands the content section as the screen widens.

Please try it out and let me know if this looks better to you so we can be confident with Gradle 4.5 docs.

Regarding customizing the interface: this would require a bit more design and implementation work, so I’d like to hold off on it until after Gradle 4.5.


(Chris Doré) #9

Thanks @eriwen,

For my usual use of the docs on a desktop/laptop, the expanded width seems to work.

Things can get a little bit wonky on a mobile device, but it’s still usable. I typically access the docs on my phone if I need to reference something when replying on the forums, or reading some of the new material when new releases are made.


(Eric Wendelin) #10

Thanks again for the feedback. I’m working on ways to make mobile experience tolerable, including changing how we deal with tables.


(Eric Wendelin) #11

Hi again Chris,

Quick update: I’ve been converting tables to a different list-style format. I hope you find this a much better experience.

Cheers,
Eric