MDN Redesign: More space for examples and code

MDN
#1

We just launched an update for our beta testers!

These changes are designed to:

  • create more space for code examples and browser compatibility data
  • make sure text maintains a readable line length

We’re taking our inspiration from how the Hack’s Blog has narrow paragraphs and wide code samples.

Some Macro Embeds Could Break

Early testing shows that some macro emebeds could have display problems. Here is an example of a broken one on staging. This is only the case when two things happen

  1. the embed content expects to have a minimum amount of space
  2. the macro is wrapped in a <p> tag.

We should not be using inflexible content. Half our users size their browsers smaller than the full width of our site. To fix the experience for most users we need to change the content.

To fix display for large monitors: edit the document to wrap the marco in <div> instead of a <p>.

Collapsing In This Article by Default

To make space we are collapsing the “In This Article” menu by default for all users. Half our users already see this collapsed by default.

The “In This Article” menu will likely be replaced with something else in the next 2 months. We like it but only 2% of sessions use it, so it’s not working for our users. Over the next few weeks we will be prototyping and testing solutions to find a better way to communicate page structure and make it easier to scan our pages for information.

We’re collapsing it now instead of waiting because we’re really excited to launch our new interactive examples and they really benifit from having that extra space. Our testers were pretty excited about them (and so are we).

Feedback

Post here if you have feedback that is qualitative or subjective, rather than something that is probably a bug. If it’s a bug, please file a bug and put “beta” in the summary field.

Thanks for using MDN,
Stephanie.

1 Like
#2

So, I waited a couple days to see if anyone else commented first, but now I’m going to share my thoughts.

I agree that we need to find a way to make more room for wide tables and examples. I am not particularly happy with certain details of the current implementation, however.

We now have body text that is restricted in width quite a bit, while other content is not, resulting in an enormous disparity in how wide things are. For example:

Screenshot-2017-8-30 Transport Layer Security
Screenshot-2017-8-30 Transport Layer Security.png1571×1090 140 KB

See how the text width varies wildly between the body text and the note and summary boxes? This is, I think, an unfortunate situation where the result is just weird to look at. Now, I know I tend to be a little sensitive about layout issues (the varying line lengths really distract me) and I personally have always preferred to have control over line length by changing my window size, instead of having a fixed line length, but even leaving those issues aside, there are definitely some design quirks here that we need to sort out.

Basically, right now, it looks like something is wrong with the layout of the body text, as if someone accidentally slapped a width on it that doesn’t match everything else on the site.

I see a few options, and I’m sure there are others that I’ve missed:

  1. Make boxes like note, summary, syntax, etc. default to the same width as the text, only getting wider if the content demands it. I would think this would more or less mean adding a min-width to them, or something like that.
  2. For parts of a document that don’t need to use the space to the right, why not make the body two columns of text, using the full width of the available space? That would give you more text visible at once while keeping the line lengths low. I expect this could be tricky to do, but if it could be done it might be an amazing solution.
  3. Make the body text flow the full width of the available space, allowing the user’s window size to control line length. This is my personal favorite option but I know it defies all the rules about “long lines are bad”. :slight_smile:
  4. Add some sort of a background to the body area (or to the empty area next to it) to help make it look less like a formatting snafu to have the body text not using the space that seems to belong to it.

As to #1, I’ve been told this option doesn’t really make sense because “these are things that are supposed to stand out anyway,” but I think the backgrounds and borders and such do that nicely, and having things stand out by looking like a layout mistake is not the best way to go. :slight_smile:

#2 appeals to me quite a bit as a second favorite and might even edge out #3 to become my favorite. Not necessarily easy to implement but it should be feasible, and it would make great use of space, while also adding character to the site by presenting the content in varying layouts between two-column and one-column depending on whether or not there’s a table or example nearby.

As for #3, which I know I’m biased toward but am not trying to push at anyone, I know this violates current principles about wide lines of text being hard on the eyes or something like that, but I feel that if someone is able to control the line length, they can choose a width they’re comfortable with. That seems to make more sense than anything else. I personally have always found long lines both perfectly comfortable to read and more convenient because I can get more content on the screen at a time. That saves me from scrolling as much while using a page as reference while working, for example.

As for #4… this is a terrible idea but it would at least help make it more clear that this is intentional. Even after looking at it for a couple of days, it still looks like a rendering error to me – like something failed to load or something.

Sheppy

#3

This is my favourite solution for the problem. I did think things were looking a little odd too, but thought I’d keep quiet for a bit, as work is ongoing.

#4

I increasingly agree. I think it would look much better and would solve my concern about being able to have as much text visible at once as possible without violating any line-length concerns designers might have.

The question is how realistic it is to implement. I’m sure it can be done (Stephanie is a wizard!), but “it can be done” isn’t always the same as “it’s realistic to do.” I hope it’s realistic, or at least we find some sort of solution, because my eyes still get very confused by the current layout. :slight_smile:

Sheppy

#5

As I understand it part of the reason to restrict width is for readability, which suggests a simple rule of thumb: if a page element contains essentially prose, it should get a restricted width.

In the screenshot you posted there are three elements that are getting full width:

(1) the draft notice
(2) the page summary section - prose
(3) the note - prose

So I think (2) and (3) at least should get the same width as the main article text. And I think with those changes, the page would look fine. (1) is arguable either way.

(BTW, I would also deprecate notes like (3), but that’s another story.)

The other way to look at this is: which elements should not get restricted width? I think this list would include:

  • code samples
  • fancy interactive editor things
  • diagrams and screenshots
  • tables
  • maybe notices that apply to the whole page, like (1) above. Maybe not though.
  • ?

The problem with a 2-column layout is that you then don’t get to use that extra space on the right. This means you don’t get extra space for things that want to be wider, like tables and code samples, but also that you can’t easily add sidenotes, which for example Stephanie talked about as a possible way to link learning area docs to reference docs.

#6

Yeah, this ^^.

Also, users expect a webpage to be linear. Scrolling back up to the top of the page to continue reading is not familiar behaviour.

I had originally let the prose elements go full width because they are a larger font so a longer line length is okay but let’s try it with just the code and tables wide for a bit :slight_smile:

I do also think I need to do something about the single column pages, which is where sheppy is seeing the most disconcerting view.

Thanks,
Stephanie.

#7

Will – Except we’re suggesting that in places where there is no content to put on the right, we use it by putting a second column of text there. In fact, I’d like to suggest we actually allow the text to gain more columns as the user makes the window wider, so that if I make my window the full width of my 5K screen, I’d have perhaps four columns, with some number of them (if not all of them) used by the code samples when I come upon them.

Having the stuff joggle back and forth width-wise is not an attractive look. I don’t think the right answer is making more things narrower. I think the right answer is to find ways to make the rest of the content the same width as the samples without breaking readability rules.

We would even then still have the ability to do things like sidenotes, by simply reserving the rightmost column for them when they become available, and when the user turns them on.

I’m trying to play with the CSS a little to mock up what I’m talking about, but am running into the boundaries of my ability to figure out how things work; I can’t even find where the width of the content column is established. :slight_smile:

Sheppy

#8

Yeah, I think it will immediately look less weird if we only have say code examples, tables, and interactive editors full screen.

FWIW, I did try experimenting with some layout ideas around multiple columns this morning, but I very quickly came to the conclusion that this will just look weirder. As Stephanie hinted at, having two columns spanning the full page length where you’ve got to jump back to the top to read the second half is horrible. The only other option would be to have each section of content (e.g. each paragraph, or list) having multiple columns set on them individually, but this makes the content harder to read and looks really awkward.

That kind of layout only really works on a newspaper, where you can guarantee that the only content will be uniform columns of text.

Another idea I had is that perhaps we could align some items to the right, like the proposed sidenotes, and perhaps notes, important messages, blockquotes, and other such things? If we had enough of these, it would serve to bring some balance to the page.

#9

Yeah, that would be a reasonable fallback position. Put the notes and certain other things in that space.

I still wish I could figure out how to make the article text full-width though. For my own purposes, that’s how I prefer my text to appear, and even if I had to hack it locally, I’d do that if I could just figure out how to make it work – but I am having trouble grokking the layout in the clever CSS used on the site right now. :slight_smile:

Sheppy