Limit line length and adjust margins for optimal readability

[fredrikekelund]

The goal was to have a line length around 75 characters and to adjust the margins to account for the fact that more headings would now include line breaks (as discussed in #293).

Since the learn3 theme inherits from the learn2 theme, and that lives in a separate repository, I thought it a better idea to simply import _main.scss here, rather than make a second PR to a theme that's no longer maintained (even though I only changed one line).

I attached two screenshots to illustrate the difference between the current site and what it looks like with these changes applied. I realize design changes are always controversial, but I hope you can give them some consideration, a limited line length really helps readability a lot.

[flaviocopes]

I don't see this being a good change honestly, as @rhukster already said in the issue linked, you can simply resize the browser / increase the font size to limit the text length, and it's adjustable as per each user needs rather than imposed.

[fredrikekelund]

I do agree that users can zoom in their browsers when we're talking about font size, but line length is another issue, and it's widely established that longer lines are harder to read. This is also something that has been considered in the design of eg. Medium, New York Times, the WordPress docs and the default ReadTheDocs theme.

I know that discussing design related things can be difficult, as they will often be less measurable than stuff that revolves around technical merit. But when talking about readability, there is an optimal line length, and it makes a lot of sense to use that as a default. If users want to, they can adjust from that, but not setting any max-width by default can produce some silly results for users on very wide monitors, and will make it harder to read the docs for users on large monitors that still fall within a common spectrum (like 1920px wide).

[fredrikekelund]

@rhukster @flaviocopes even though I personally would really love to see this merged (I really think it's a big issue with the docs right now), I'd urge you to consider this primarily from a usability perspective - readability is a key feature of any documentation, and line length is critical to ensure readability.

Of course, things don't have to look exactly as I submitted them here. For instance, the lines could be slightly longer if you feel strongly about that, or the "Edit on GitHub" header could be extended to cover the full width of page to balance things a bit. My main point here was just to give you a merge button to be able click easily if I could manage to convince you that this was a good idea ;)

[fredrikekelund]

Any thoughts on this? I want to puff this Smashing Magazine article that I mentioned in #293 again as an argument for merging this. And please note as well, that this PR doesn't decrease the body font size.

[vineyardbovines]

Optimal readability is ~12 words per line. Here, on a 2000px monitor, there are about 40 words. On a laptop, lines cap out around ~20 words. It's something like only 30% of users actually read things. I would say that wrapping the content at ~1200px would be a good idea, simply because it'll be a bit easier to skim and users will be more apt to actually read it.

I don't agree with the proposed margin/padding changes because they seem pretty asinine. 2rem to 1.7rem? That seems unnecessary. Also, optimal line height is between 1.3 and 1.6-- 1.25 is too small. I believe that setting a proper line height will fix any vertical rhythm issues.

[fredrikekelund]

@gretzky I'm open to making the lines a bit longer, but I felt that the 46em max-width in this PR made for a pretty comfortable reading experience with around 70 characters per line.

Regarding the margins, 1.7rem is what's used for the paragraphs currently. That number may seem a bit random, but this change merely harmonizes between margins of <pre> elements with <p> elements. The line-height change also only affects headings.

[simonhaenisch]

Simply wrapping everything in a max-width container isn't a good solution imo.

A few things look kind of bad:

• right arrow floating around in the middle of nowhere
• the nav bar on the top doesn't cover the full width (which is why you removed the breadcrumbs nav?)
• tables look a bit to narrow imo

For inspiration have a look at these docs, which I think are very well designed: https://developers.squarespace.com/beginner-tutorial/

[Duke3D]

Extensive testing has found the maximum line length for optimum readability to be 65 characters for most fonts and media. Longer than this and the eye loses track of which line it is on as it returns from right to left. Optimum is 50-60 characters. A max-width for the container measured in equivalent rems is an efficient way to implement this objective without interfering with responsive flow on smaller or zoomed screens. (Using non-breaking spaces is an efficient way to manage line breaks that cause floating arrows.)
When it comes to documentation, IMO, readability is more important than aesthetics.

[simonhaenisch]

@Duke3D aesthetics can help increase readability a lot, so it's not a either/or 😉 But yeah don't make it look nicer at the cost of readability. I'd put a max-width on paragraphs/headers rather than the website container.

Example:

h1, h2, h3, h4, h5, h6, p, li, pre {
    max-width: 40rem;
}

Tested it for a few pages and seems to be working well (most stuff is wrapped in a p).

[fredrikekelund]

@simonhaenisch that looks like a totally valid solution as well. If the maintainers would like that better, I'm happy to edit the PR!

[fredrikekelund]

I still believe that limiting the line length is a good course of action, but there's no point to keeping this PR open if won't be merged. Can't promise that I'll be able to make edits if you want to merge it in the future, perhaps it's better if the core maintainers implement the feature should they decide they want it.