Limit Width of Content

[pradyunsg]

cf: pypa/pypa-docs-theme#9

Currently, this theme allows for the content to extend to the complete width of the page. This results in some extremely bad UX since essentially there are lines of text stretching across the entire width of your screen.

Limiting the width of the content would create a nicer reading experience.

[pradyunsg]

Ping?

[JulienPalard]

I agree, I though the "limit" was like 70 character per line for a comfortable reading.

I'm no CSS expert but if an em is a character "box" and the ratio of the box in unpredictable, then it's hard to set the line width in term of number of characters.

Look like 35em yields like 75 chars per line with our font, which gives this "thing":
https://screenshots.firefox.com/348ppi53g4wnbizz/docs.python.org

For code blocks readability, I think we should allow for like 80 characters, as code blocks can easily go after 80 chars. An em of 45 gives exactly 80 chars per line in code blocks, but lines of 98 chars (https://screenshots.firefox.com/VGc6S3SUY0sdGo3Q/docs.python.org) which is too much, but better than whole screens, we make diverge the size of text and code blocks to search a nice mid-point.

[methane]

FWIW, https://developers.google.com/web/fundamentals/design-and-ux/responsive/#optimize_text_for_reading

[JulienPalard]

Asked to a few friends (thanks Bruno, Antoine and Florian), they proposed this:

What do you think?

[methane]

It's much better than now.
I feel header width should be limited too, with little larger max-width.

[pradyunsg]

Hi @JulienPalard and @methane!

@JulienPalard that is indeed what I was visualizing. Further, I agree with @methane that even the header should be limited in width, except I imagine that would cause issues with the search bar and navigation.

[JulienPalard]

@Mariatta Any feedback on this?

[freddrake]

On Wed, Dec 20, 2017 at 9:14 AM, Pradyun Gedam ***@***.***> wrote: I agree with @methane <https://github.com/methane> that even the header should be limited in width, except I imagine that would cause issues with the search bar and navigation.

I don't even have a clue how many nights I lost trying to get navigation bars right with the Python docs. Limiting the width of the header is definitely going to exhibit problems, but nothing that won't also be a problem if you use a window that's reasonably sized for the content width. We have that problem now, so I'm not convinced it should be considered a blocker. ​ -Fred

…

-- Fred L. Drake, Jr. <fred at fdrake.net> "A storm broke loose in my mind." --Albert Einstein

[terryjreedy]

I have a wide-screen monitor and " Python » Documentation » The Python Standard Library » 18. Interprocess Communication and Networking » 18.5. asyncio — Asynchronous I/O, event loop, coroutines and tasks »" with embedded language and version boxes (which is a bit ugly) + the | index | modules | next | previous | buttons take up most the width. The search box is on a line by itself, below the gray separater line. I think the language and version boxed are in the wrong order and misplaced -- see mockup below.

If I narrow the window to what would be the content width, the title is wrapped onto the second line, with the search bar, with the separator line moved down. Not nice. A more balance design would give the top line a constant, shorter width.

Python |_version_| >> Documentation |__language__| [quick search] |index|...|prev|

The second line, with the changing title, which should always be above the gray separater, would usually fit the width you want.

The Python Standard Library » 18. Interprocess Communication and Networking » 18.5. asyncio — Asynchronous I/O, event loop, coroutines and tasks »"

Let the browser wrap the second line when necessary. That should not be often, as the chapter and sections titles in this example are both longer than usual. The title line would fit without wrapping even more often if the redundant prefix 'The Python' were omitted.

[Mariatta]

I don't like the empty gray space that is in the screenshot.
And it seems odd that the menu bar extends the entire screen, but the content does not.

[freddrake]

Looks like my earlier comment lost the screen shot from my email:

[ghost]

Agree with you @Mariatta , need one color for the menu and another for the empty space on the right.

[JulienPalard]

@BrunoMaugery Any color idea we should try?

[JulienPalard]

@freddrake Agree, we spotted too the search box wrapping under the separation line while working on this issue, but considered it's another one, so I'm opening it to track the discussion #7

[pradyunsg]

I found some time and took a stab at actually making the browser show what I was thinking.

(the example is from pip's documentation; it's using this theme with some sidebar + topbar changes - see pypa/pypa-docs-theme)

[freddrake]

@JulienPalard Thanks! Issue #7 is really only interesting if the entire header design isn't being re-constructed. As long as it's all handled in the end, I'm happy.

[JulienPalard]

I always though, too, that limiting the line length to around 70 was a typographic choice for readability (I first encountered it in LaTeX) but researching on the subject I found: https://web.archive.org/web/20150619221256/http://psychology.wichita.edu/surl/usabilitynews/72/LineLength.asp which states:

Results showed that passages formatted with 95 cpl resulted in faster reading speed. No effects of line length were found for comprehension or satisfaction, however, users indicated a strong preference for either the short or long line lengths.

Sadly the experiment didn't included longer line length...

Also:

One of the first studies with computer monitors (Duchnicky and Kolers, 1983) found that longer text widths resulted in 28 percent faster reading times over narrower text widths. Other studies (cf. Dyson and Kipping, 1998; Youngman and Scharff, 1999) continued to show that reading rates increased as characters per line increased. These same studies have reliably shown that users prefer shorter line lengths (about four inches).

(https://www.usability.gov/get-involved/blog/2006/08/line-length-and-onscreen-reading.html)

[JulienPalard]

Maybe, a max-width of 1024 is too restrictive (gives ~90 CPL). Limiting it to 1440px gives ~140 CPL, without generating a huge white block on the side (on my 1920×1080 screen):

https://screenshots.firefox.com/bYuA7MHQXmOVNkm8/docs.python.org

[Ivoz]

@JulienPalard note that all your studies, as far as I could tell, are only considering the merits of line lengths under 100. Currently on my 24" 1080p screen, python.org's line length is 220. Staggeringly out of bounds of their considerations.

The main reason such absurdely long line lengths become unreadable is our eyes have to trace all the way along the line to read it, then make a huge accurate jump back to the beginning of the next line. With shorter lengths this jump neither is as big, nor does its angle need to be as accurate to correctly focus on the next word. If your screen width angle is large enough (mine is, as mentioned above; may not be a problem for a smaller 15" 1080p laptop screen for instance) you can find your eyes moving out of their most comfortable 'central zone' and wanting to turn your head instead, to follow the words, which also then means physical head turning just to read.

It also means finding separate sentences or particular words is harder, as our eyes have to do way more horizontal scanning in addition to vertical scanning (with much shorter CPL we can more easily scan the paragraphs / sentences with smooth vertical scanning and only short horizontal sweeps if any)

Aesthetically I'd say it also makes single (or even double) sentences look sparce; it also comes from a familiarity standpoint. Apart from other unformatted web pages whose text just spans as large as the browser, encountering large line spans is not something we're used to either, making it inherently unfamiliar and uncomfortable.

TL;DR Pick any CPL number you like under 100, and it would be a massive, massive improvement to the current situation.

[methane]

FYI, sphinx-doc/sphinx#4246

[methane]

And https://github.com/sphinx-doc/sphinx/pull/4376/files

[JulienPalard]

Has been fixed upstream in sphinx-doc/sphinx@bf29ffb and we have updated our sphinx-doc version since python/docsbuild-scripts@6c37795, so we're having it applied in production, see: https://docs.python.org/3/reference/datamodel.html.

[lightmare]

I found this issue when trying to figure out what's "wrong" with pythons docs. After years of perusing full-width docs, having literally half of the page blank looks ... weird.

I may be an outlier, but I don't often read the docs. Much more often I find myself looking for a specific method on a page I'm somewhat familiar with already. For example when I had docs for some module open and forgot what arguments method X.Y accepts, full-width page required less vertical scanning (and scrolling) to skim through method names.

Previously I had the option to shrink the browser window if I wanted to read large chunks of text, or keep it at full width for fast scanning. Now I don't have the latter option.

Second issue I have with this change is that it keeps text-align: justify. With reduced width the text layout has fewer opportunities for line breaks, which results in wildly varying spaces between words, and it looks terrible. Just changing the style rule in browser to text-align: left makes the docs look better, and more readable imo.

[JulienPalard]

@lightmare Hi! Thanks for your feedback. I'm still not sure limiting the width is a good idea, I had not found relevant studies on the subject, the few studies I found did not prooved that limiting the line width was in fact good for readability. (And I can understand reducing the line width hurt readability as the number of line breaks is increasing).

Feel free to open a new issue on the subject of not limiting the line width so we can gather feedback, and an other issue about text-align too, feel free to mention me in those issues and @BrunoMaugery in the issue about line-width, he's my mentor about graphical concerns.

[terryjreedy]

This change removes the freedom of users to select the line width they want. Some of us are not happy about it. See https://bugs.python.org/issue34006. Sometimes, there is a good reason to want wide lines. In some cases, the result is terrible. See https://bugs.python.org/file47662/NarrowCHM.png. Anyway, I added a note that the change is a side-effect of updating sphinx-doc and that a new issue is needed to modify that for us.

[theacodes]

Is there anything actionable we need to do here?

…

On Sat, Jun 30, 2018, 1:36 PM Terry Jan Reedy ***@***.***> wrote: This change removes the freedom of users to select the line width they want. Some of us are not happy about it. See https://bugs.python.org/issue34006. Sometimes, there is a good reason to want wide lines. In some cases, the result is terrible. See https://bugs.python.org/file47662/NarrowCHM.png. Anyway, I added a note that the change is a side-effect of updating sphinx-doc and that a new issue is needed to modify that for us. — You are receiving this because you are subscribed to this thread. Reply to this email directly, view it on GitHub <#4 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AAPUcz5EkyqbUqxlskmTf6xjGX9czB6cks5uB-FXgaJpZM4QZcg6> .

[terryjreedy]

As Julian said April 28, locally disabling the limit would be a new issue.