Three.js: Adjust the spacing or font size on the new docs?

[greggman]

Description of the problem

Sometime in the last hour or so the style on the docs got updated.

Things are about 20% more spaced out which I personally find far less usefull. I'm certainly not against new styles but just a vote that this style doesn't make the docs more readable it makes them less, at least for me.

old:

new:

In fact it's funny, the new docs have a larger font but end up with less whitespace both in terms of actual whitespace and in terms of proportional whitespace which I think is one reason it appears much less readable. Of course adding more whitespace so it's the same proportions as it was would put even less info on the screen. In any case, just pointing out that the smaller font with the larger whitespace made it more readable for me since areas were separated more.

Maybe it's all just personal preference but I also prefer code to be in a monospace font. Not suggesting the paragraphs of text be monospace, only API names if possible.

I know this is all subjective, just my 2¢ since I reference the docs several times a day.

[moritz4]

New styles always get some getting used to, but for me the font is far too large for the page. Readability has suffered greatly under this change I think.

[titansoftime]

but for me the font is far too large for the page

Agreed. Now if my monitor was 6 ft away, it would be great.

[greggman]

I'm old and my eyes can't focus well . I still find the old style easier to read. I think it has to do with whitesapce. the new style has it all spread out such that the different paragraphs blend into a blob my eyes can't figure out. the old style with more distinct gaps between paragraphs and sections gave my eyes places to anchor

[gkjohnson]

I always like to give things a try for a bit but at the moment I'm finding myself consistently zooming the docs pages out to 75 or 80% scale so I can read them more easily. I think in general I don't find myself reading such large text on the web so the switch when opening the docs is pretty jarring, as well.

[donmccurdy]

Note that there's a significant dependence on breakpoints here – in r105 I thought the text was too large on my 27" monitor but looked right on a laptop. As of r106 I'm quite happy with the font sizes at all breakpoints, the issue with the largest breakpoint is fixed from my perspective.

If folks have concerns about the latest updates, it might be helpful to know the window resolutions involved. External guidelines do exist for font size, contrast, and line length, and — while the typography choices in r106 docs appear good to me — feedback with respect to accessibility standards is always welcome!

[gkjohnson]

Note that there's a significant dependence on breakpoints here – in r105 I thought the text was too large on my 27" monitor but looked right on a laptop. As of r106 I'm quite happy with the font sizes at all breakpoints, the issue with the largest breakpoint is fixed from my perspective.

Oh interesting! I didn't realize there were css media-query selectors that changed font-size. For what it's worth I still feel it's too big even in the new revision but I do see that it's better when I make my window smaller. I'm not sure I understand why font-size is being dictated by the width of the window -- shouldn't that be pixel density dependent, which the browser should already be handling? Is that a common practice?

Here are the specs of the monitor (Dell U3415W) and window size that I'm typically using to look at the docs:

• Monitor Resolution: 3440x1440
• Monitor PPI: 109 ppi
• Browser Window Size: 1763x570

This means that I'm hitting the media query where the font size is 18px. I think my preference would be to remove the query that sets the font size to 18px and make it 16px (or even 15px like it was before) regardless of window size.

the issue with the largest breakpoint is fixed from my perspective.

Can I ask how it was fixed? I see there's a commit that moves the max-width query from 1500px to 1700px last month but I don't see anything else that would have changed the font size recently.

Thanks!

[donmccurdy]

Can I ask how it was fixed? I see there's a commit that moves the max-width query from 1500px to 1700px last month but I don't see anything else that would have changed the font size recently.

Comparing r105 and r106 now, I guess they look pretty similar actually. Maybe my eyes just got used to it haha. In any case –

I'm not sure I understand why font-size is being dictated by the width of the window -- shouldn't that be pixel density dependent, which the browser should already be handling? Is that a common practice?

The browser handles pixel density concerns well, yes, but viewport width is still relevant to typography choices. This article on Responsive Website Font Size Guidelines summarizes it pretty well I think. 16px is generally a good starting point, but larger fonts may allow easier reading in text-heavy pages, balanced against line length – too long or too short makes reading harder. So decreasing body text size somewhat on smaller screens is a common enough choice.

But line and section spacing are probably the more important factors here — if folks feel like the docs are a bit harder to scan with these changes, (1) reducing font size alone probably won't help anything, and (2) some small changes to line spacing probably would.

Comparing r103–r106, at 1440x900px:

| version | screenshot |
|---|---|
| r103 | |
| r104 | |
| r105 | |
| r106 | |

[donmccurdy]

Comparing text-heavy pages like the long-form Manual sections, the new styles look significantly better than the old and have no readability issues from my perspective. Comparing API documentation like the screenshots above, I could see the argument that this is a bit harder to scan through than before. I'm having a hard time pinning down why that is, but I think maybe the spacing between different methods is too similar to the spacing between method descriptions and the method names/parameters they describe? Taking a shot at a tweaked version of the page above:

^That said, the changes above do _not_ have a positive effect on Manual pages, and we don't currently have any way to isolate style changes to the API documentation. That's probably part of what made this tricky the first time around, and could be fixed, but might be a big PR. 🤔

My edit definitely has too much space beneath the largest headers...

[gkjohnson]

Great thanks for laying all this out and for the article! I hadn't looked at the manual pages like "Creating A Scene" and to me it's clear that the font size improves the readability of those pages.

Comparing API documentation like the screenshots above, I could see the argument that this is a bit harder to scan through than before. I'm having a hard time pinning down why that is, but I think maybe the spacing between different methods is too similar to the spacing between method descriptions and the method names/parameters they describe?

I think for me this is what I'm noticing the most. If we need different styles for the api pages can't we just add an api.css file that overrides a few different styles that are specific to the api pages? That would be the simple change, at least, but maybe not the preferred one. Your changes definitely look like a good start!

[sciecode]

I really like @donmccurdy style tweaks.

Both larger spacing and smaller font-size for methods help define a more concise visual hierarchy.
It's way easier to scan through the documentation and understand which information belongs where.

[caspercasanova]

Another suggestion is adding a max width using the character ( ch ) value in css. If you set p: max-width: 60ch; then it will change the width of the element to length of 60 characters long ( using the width of the fonts 0 for measurement). I generally shorter lines improves accessibility and readability.