[Bug] Width of the Solidity docs site is artificially constrained.

[MicahZoltu]

Description

The docs site has an artificial limit on the width, which results in a massive waste of screen real estate and has some problems with overflows and horizontal scrollbars in several areas. The page should fit the browser width, and if the user wants something slimmer they can shrink their browser window rather than dictating that everyone must suffer equally (emphasis added because people always bring this up as a "problem" with auto-filling space).

Environment

• Compiler version: N/A
• Target EVM version (as per compiler settings): N/A
• Framework/IDE (e.g. Truffle or Remix): N/A
• EVM execution environment / backend / blockchain client: N/A
• Operating system: Firefox

Steps to Reproduce

View the Solidity docs at https://docs.soliditylang.org/en/v0.5.8/using-the-compiler.html#using-the-commandline-compiler Note the overflowing text and ridiculous amount of whitespace: Note the horizontal scroll bar and ridiculous amount of whitespace:

---

Same screenshots with a single CSS change:

[cameel]

Personally, I also wish it worked this way. There's a lot of space wasted even if my screen is wide enough to show more. And the content is not even centered.

On the other hand, I don't think it's really a bug - seems to me to be a deliberate choice in the theme. I think it's the default for the RTD theme and lots of other projects do this with their docs. Probably for readability and because it does look neater in places where things are not wide enough to require horizontal scrolling.

What do you think @franzihei?

[franzihei]

While I personally agree and would also prefer the wide-screen version, I think this is done on purpose by the theme to optimize for readability. E.g. see https://blog.soliditylang.org/ (or https://ethereum.org/en/developers/docs/ or https://doc.rust-lang.org/book/title-page.html) where the posts also have a fixed width, which makes the text much easier to read.

I'm still happy to explore adjusting the total width of the text blocks, but maybe there is a way we can make this optional? E.g. by double clicking on the text to expand it, or by adding another mode?

This change will otherwise highly influence the legibility and will probably also break some design best practices on how to structure text blocks (not a designer here though).

[axic]

To provide feedback from another angle: I would find it tiring to move head/eyes 50 centimeters across should it be fully expanded. Yes, I could resize the browser window too, so it is not a strong limitation.

That being said likely increasing the width to match current common screen sizes could be a good idea.

[MicahZoltu]

This change will otherwise highly influence the legibility and will probably also break some design best practices on how to structure text blocks (not a designer here though).

It only influences the legibility for people who only know how to use their browser fully maximized and have a widescreen monitor. I would hope the target demographic of this page are people who know how to resize a browser window. 😅

The actual design best practice is to have your page be responsive to the environment the user is using, which means shrinking/expanding based on available real estate. For accessibility reasons, you shouldn't assume everyone is viewing the site with the same resolution, font size, zoom level, etc. and at the moment if the user increases the font size (but not zoom) things get even worse and the user cannot compensate by increasing the width of their browser window. Unfortunately, most designers are incredibly lazy and build websites like PDFs where they are only usable at a specific well defined resolution/font/size.

[franzihei]

Even this very website you are using right now has a fixed width 😉

[franzihei]

I'm getting some more feedback on this and will come back here soon!

[MicahZoltu]

I have a bookmarklet for this site that removes the hard coded width, and if GitHub had a public bug tracker I would have filed a bug years ago about this.

That being said, just because other people on the internet do a thing doesn't mean it is a good idea. 😀

[samajammin]

I'm personally a fan of enforcing some max width on the container to limit the width of any given line of text. Seems to be a common UX approach across the web, e.g. Google, NY Times, Medium, MDN (although there's certainly counterpoints, like Wikipedia). Enforcing a max length of lines of text tends to improve readability.

FWIW you can see we do this on ethereum.org: Although you'll see we do still have some open discussion on this: https://github.com/ethereum/ethereum-org-website/issues/4026 - I think in general it's a widely debated topic & different people have different preferences.

[minimalsm]

Depending on who you ask, the optimal line length for the web is somewhere between 50-85 characters. Any more or less can hurt readability.

People generally read about 1/4 of the words on a webpage, so shorter line lengths are better to let users skim.

I agree with the issue that the current layout isn’t ideal and having to scroll code blocks is annoying, but the proposed solution of having no width constraints and allowing the line length to grow arbitrarily would make the website significantly worse for most users IMO.

[MicahZoltu]

People generally read about 1/4 of the words on a webpage, so shorter line lengths are better to let users skim.

Shorter lines make skimming harder because you have to scroll further between section headings/paragraphs.

Depending on who you ask, the optimal line length for the web is somewhere between 50-85 characters. Any more or less can hurt readability.

I challenge the claim that 50-85 characters is optimal, and even if it is true: A. The user can set their browser width to whatever they want. B. Number of characters is not a function of number of pixels unless the font size is fixed (which it isn't for anyone with accessibility settings that change font size) C. It is highly unlikely that there is a single optimum for all use cases. Reading a novel is quite different from reading an encyclopedic article or reading a docs site.

I personally find the docs site notably better with the change I implemented (can be enabled against live site with a simple CSS change), so at best one could argue it is subjective. For docs sites I rarely read entire lines, I skim through looking for section headers or code blocks that have what I'm l,oking for and then usually just read a code example. It is quite rare that I actually read (in the traditional sense, like a novel) anything significant.

[github-actions[bot]]

This issue has been marked as stale due to inactivity for the last 90 days. It will be automatically closed in 7 days.

[MicahZoltu]

I would still like to see this change made. If the current maintainers think it is a bad idea I think it would be better to close the issue with a comment saying as much rather than letting it go stale.

[franzihei]

Fair point! I think there are a couple of things that we recognise could be better about the docs, but I don't agree that this fix in the current doc framework will improve the experience. So for now, I'd say let's close it. However, the problems you pointed out re. needing to scroll a lot horizontally in code boxes should definitely be kept in mind when applying design changes (or framework changes) to the docs in future. Improving the docs framework design- and UX-wise is something I have on my wishlist of things to improve eventually.