An improved readability experience that is also more accessible

[schalkneethling]

Hey everyone!

I have been working on some changes to the readability and accessibility of MDN Web Docs. It is now at a stage where we would love to get your input on the changes. To do that, here are the steps.

1. Use MDN Web Docs as you normally would but using the following URL: https://5546.content.dev.mdn.mozit.cloud/
2. Should you find anything that can still be improved, please add a comment here describing the problem you encountered.

I will read over each comment, create a new issue and address these as appropriate. At least once a day I will release an update and post the changelog here in the discussion. Thank you in advance for being part of the evolution of MDN Web Docs.

[AleksandrHovhannisyan]

Overall, this update looks great! Definitely an improvement over the current version.

I haven't looked too deep into the content yet (I can take a closer look later this evening), but here's just some general feedback:

Article paragraph spacing

The current line height of 1.75 looks great! 👍

What are your thoughts on decreasing the paragraph spacing to 1.75em after? The difference is very subtle (especially in the zoomed-out images below):

Before (line-height: 1.75, margin: 1rem 0 2rem)	After (line-height: 1.75, margin: 1em 0 1.75em)

Note: Either way, I would probably use ems in case we change the paragraph font size in the future. That way, it's relative to the paragraph font size rather than the root font size.

Featured articles tiles

I think we might want to tighten the line height for the tile descriptions since the line length here is shorter than elsewhere.

Would it be possible to add an intermediate design variable for line height, maybe 1.5 or 1.6? Here's a before-and-after:

Before (line-height: 1.75)	After (line-height: 1.5)

Dark mode links containing <code>

Note: I'm not sure if this was originally reported/logged as part of this epic. If not, and if we agree that this should be investigated, we can open a separate ticket for this.

On the HTML pages in dark mode, links containing <code> almost look like red underlines for grammatical errors, like what you'd see in Word/Google Docs. The effect is especially noticeable in my peripheral vision. When I look at the links directly, I can tell that they're underlines.

This will likely vary from one user to another, but I wonder if it would cause confusion for other readers too or if it's just a problem with paragraphs where there are lots of links.

[schalkneethling]

Thank you for the feedback @AleksandrHovhannisyan. Much appreciated.

[spartanatreyu]

I think there's another problem with the featured articles tiles. Looking at the titles of the pages through mdn, it seems that half of the pages have titles of 1-2 words (things defined from web specs), and the other half has longer titles of either longer words or many smaller words (guides, tutorials, plain old long titles).

It might be better to not have every tile be the same size, to make it easier for larger titles to fit into the pages.

Here's what I saw after 2 minutes of tweaking the homepage with a simple 2fr 1fr grid column layout:

I'm sure this layout could be readjusted like a manual masonry grid layout as different pages are featured and removed.

Another tweak might be an underline under the titles of the tiles that match the colour of the section of the website they go to.

---

I definitely agree with the hyperlinks in <code> elements in dark mode not looking like hyperlinks.

To me it looks like the code blocks have automatic syntax highlighting on them that is erroring out. It looks like a whole bunch of errors of elements not having closing tags.

[Mitsunee]

Would it be possible to add icons for the browsers in the Browser Compatibility tables? While I understand the reason for the rotated text I find it hard to match rows further down the table to the headers because I have to turn my head slightly to be able to read them.

Comparing with the current production version of the site I really like the bigger font size especially for the sidebar and code blocks, but I am not sure if I'm a fan of the brighter darkmode colors.

[schalkneethling]

Hey @Mitsunee, this has been added.

[Mitsunee]

Looks good, but the Firefox icon does not seem to display on my end. Seems to be a CSS issue in chromium based browsers (it's used the -webkit prefix fallback according to the devtools). My browser reports as Chromium: 100.0.4896.79 (Official Build) (64-bit) if that helps narrow it down.

[schalkneethling]

ah yes, that has been fixed. I need to do another deploy of the latest code.

[schalkneethling]

Hey everyone!

A new version of the readability project has been pushed to https://5546.content.dev.mdn.mozit.cloud/. Please keep your feedback coming.

[spartanatreyu]

Alert background contrast:

---

Code block theming:

Brackets are usually quite bright compared to their backgrounds since missing a single bracket can break a program.

Example: https://code.visualstudio.com/assets/home/home-screenshot-mac-lg-2x.png

---

Code block readability:

Background color is far too similar to brackets, comments, and blue statements. Making the code block darker than the surrounding content makes this code theme easier to read.

[schalkneethling]

Thank you @spartanatreyu. These are on my list to attend to today.

[adrianthedev]

One of the things that I'd like to have back is the old zillaslab font. All the headings and special title stood out a lot better than the current font. I think it's the serifs that made the difference against the other font that's sans-serif.

The new version posted above looks better BTW. GG!

[schalkneethling]

Hey Adrian, unfortunately, that is no longer an option for us. We are aligning more closely with the overall Mozilla brand and for the most part, we have moved away from Zilla for general use cases. I am glad that you find the updates to be a step in the right direction. I did try to better implement that hierarchy with the use of a much stronger bold for h1 and h2 heading elements.

[adrianthedev]

Yeah, I noticed the new heading. IMHO that's still "bland". Still don't distinguish themselves from the rest of the content as well.

I understand the brand alignment desire, but maybe this is a conversation that should be had with that design team that made the initial "brand book" and take these issues into consideration.

[rogix]

Not necessarily related to readability, but definitely affects the user experience.

When navigating to other pages in dark mode there is this flashing between the pages. I didn't investigated the issue deeply, though, but I think is important to have this fixed before launch. I'm experienced with open source projects, but I let me know if I can help.

[visualnaut]

+1 with this issue, plus in my case, the page is showing in a light mode for a second before it changed to dark mode again.
I think this is because my system color preferences is light and the site is dark.

So it set based on my system preference first then override with website theme when it finish loading because it also happened if I switch the config (system pref dark, web theme light)

CleanShot.2022-04-07.at.17.46.30.mp4

[schalkneethling]

Interesting, thanks for highlighting this.

[stucox]

How about a font that clearly distinguishes I, l & 1?

[schalkneethling]

Indeed @stucox. After having tested it myself, I have brought this up with the rest of the team.

[schalkneethling]

Hey everyone!

A new version of the readability project has been pushed to https://5546.content.dev.mdn.mozit.cloud/. Please keep your feedback coming.

This iteration includes some updates by me as well as code and idea contributions from the community. Thank you to everyone for your continued feedback. ❤️