MDN Redesign: Improving article scanability

MDN
#1

Hi All,

We just finished a round of user testing on two designs intended to improve the scanability of pages and help people understand the structure of our pages better. I wanted to provide an update for those who are curious.

A few interesting things we learned:

  • Regular users have a really clear mental model of our page structure.
  • People are not unhappy scrolling around the page to find what they want.
  • Hardly anyone uses the “In this article” section, and those that do only use it to get to a part of the page they already know is there.
  • Testers interacted with the line-length changes that are currently in beta without remarking on them. (Except one who said it was easier to read without being able to say why they felt that way.)

As testing moves forward we’re going to:

  • Move forward with the line-length changes currently in beta which give us more room for code examples.
  • Remove the “In this article” section from all pages.
  • On reference pages, make links to common sections available in a new format.
  • Improve the ability of users to find headings when scrolling up and down the page (this will benifit the Learning area too!).

This is the “round 3” version that we are testing today:

r3-articles-short
r3-articles-short.png1556×1542 269 KB

If you want to see it yourself it’s on staging until 11:30 Pacific Time. Remember it’s a prototype, we’re not looking for bugs reports.

Some things we’re still thinking about:

  • This works best when people know what sections are on the page. How do we handle pages which have unfamiliar sections? (Example: Array generic methods)
  • How does this work with narrower screens?

Thanks,
Stephanie.

2 Likes
#2

This version is really wonderful. I love these changes. I love the “jump to” bar at the top (although I wonder if it should be more ocmpact) and the blue lines above the

s are gorgeous.

And the sidebar is also much nicer now.

I’m ecstatic about the direction this is taking!

Eric Shepherd

Senior Technical Writer, MDN

MDN: https://developer.mozilla.org/

Blog: https://www.bitstampede.com/

#3

Hi All,

Here’s an updated screen cap of what we’re pushing to beta next week:
03-fullpage

The “Jump to” menu appears on any page that currently has a Table of Contents. Its generated from the <h2>s in the article.

This works best with a small number of h2s on pages that follow a predictable format. Reference pages work best. Lots of the learning area works well too.

What do we do with long menus?

  • Menus longer than 2 lines will not “stick” to the top of the screen.

What do we do on small screens?

  • Screens shorter than 680px will not get a sticky menu.
  • It does not appear on mobile, instead each section is hidden by default and the heading can be tapped to toggle it open.

12-fullpage
Screen Shot 2017-11-07 at 22.17.12-fullpage.jpg160×611 32.2 KB

Editing the “Jump to” menu

  • Remove the menu by editing the page > “Edit page titles and properties” (under the page title) > TOC > “No table of contents”.
  • Decrease the size of the menu by grouping sections together under a single heading. For example: Gecko-specific notes could be a h3 under Browser Compatibility, or Srcset Example and Sizes Example could be h3s under Examples

Feedback

  • General feedback is welcome here.
    - File a bug for specific functionality problems.

Things we would like to know!

  • Does it get in your way?
  • Does it work well on more pages than it works bad on?
  • Are there any areas we should turn the menu off by default?

Thanks,
Stephanie

1 Like
#4

Maybe you could rename “In this article” to a more standard “Table of contents” or like on Wikipedia “Contents”. Maybe some people don’t use it because they are not sure what it is?

I think removing ToC would be a bad idea. Yes, for most of the cases I can just read the definition and hit End to go to browser support. But for guides the structure of articles vary and I may want to go to some section in the middle or glance on sections to see what’s described in the guide. Also note that on mobile going to the bottom of the page is fastest through ToC as you have no End key.

#5

FWIW, this is how it should be getting done anyway. :slight_smile:

Sheppy

#6

This is how I feel as well, but unless unexpected new data arrives, removing the ToC does seem to be the right course of action for most users. For me, it will be an enormous hassle, since I rely so heavily on it. That said, it should be relatively easy to create a browser extension that collects headings and insets a ToC somewhere useful in the page or even in the browser UI (like the sidebar, or in a drop-down menu, or something). That would let those of us that rely on the ToC have at it again.

I personally don’t feel it’s the best solution (having to resort to an extension to get a feature as fundamental to the reading experience as a table of contents), but I can’t argue that the numbers don’t suggest that getting it out of the way makes sense. That said, I would rather have a drop-down menu ToC either instead of or in addition to the jump bar. But we are outnumbered. :slight_smile:

Sheppy

#7

Love this new “sticky” “Jump to” section :slight_smile:

#8

I like the look.
The style is nice, that is, as long as it does not get larger than two rows.
Then it becomes too big.
Maybe on mobile (I am working from a tablet) you could include a swipe to left and right to move the items in the Jump To bar. Edit: maybe make it draggable with the mouse as well or with arrows on the ends and leave it in one row.

The grouping of headings would be a good way too, so there are not too much links in the Jump To bar.

#9

Hi all,
I’m really curious here, I don’t understand the actual trend of putting sticky horizontal bars everywhere. Sorry if my tone is harsh, this is not my intention.

I mean, screens get larger and larger and we keep eating up vertical space, this does not make any sense. At first I thought this was for mobile devices, but:

What do we do on small screens?

  • Screens shorter than 680px will not get a sticky menu.
  • It does not appear on mobile, instead each section is hidden by default and the heading can be tapped to toggle it open.

Can’t we just use media queries or something, to push the ToC to the side when there is enough space?

#10

Hi Waitlin,

Thanks for weighing in. We need the horizontal space for the new interactive editors. In our user testing sessions almost nobody noticed or used the TOC on the side. The TOC on the top didn’t see much engagement either, but it also didn’t get in people’s way. We could be more flexible, but that would increase complexity for some rather fringe cases.

If we don’t see engagement in production, we can of course re-evaluate again.

#11

I think it would be of benefit to be able quickly filter out those methods and properties of a coding language that are depreciated or abandoned as the language developed.

As an example a filter/toggle button above the JavaScript Built-In String listings would hide things like:

String.prototype.anchor()
String.prototype.big()
String.prototype.blink()
String.prototype.bold()

I believe this feature would both enhance the “readability” of the article and encourage best coding practices. Your thoughts?

#12

I think the “Jump to” bar is much more successful on reference pages than on guide-type pages. For example:

versus:

A lot of this is, as you say, because reference pages have a much more consistent structure. It’s also (relatedly) because guide-type articles are more likely to be intended to be read through start-to-finish, and reference type articles are intended to be organized for quick retrieval of bits of content - examples, or syntax, or compat.

#13

Yes. I think @Stephanie_Hobson brought up something similar a while ago, with the example of the page for <td>, which mixes up deprecated and current attributes all together.

I think the UX is tricky though, I’m not sure a control to hide them is ideal. But even just grouping them in a separate section would probably help.

#14

We do plan to split out all the deprecated stuff into its own “Deprecated attributes” or “Deprecated methods” sections over time within the various reference overview pages. It’s already been done in a few places. See the <tr> page for an example; note the separate “Attributes” and then down below a ways “Deprecated attributes” sections.

I generally encourage anyone editing pages with lists of attributes, properties, or methods to do this – move all the deprecated or obsolete stuff into a new section called "Deprecated ".

Sheppy

#15

I should also note that there’s more that we’ll be doing to pages such as the HTML element reference pages to make them more readable; I was just commenting on this one specific issue. :slight_smile:

Sheppy

#16

While this new navigation structure is interesting it has made quickly helping people even harder, since you can only easily get anchors to top level headings now. Previously you could at least get some sub levels (some anchors you still had to just know about). I’d love it if there was an easier way to copy anchors from MDN headings to point people to the correct part of a guide etc.

EDIT: Made a quick extension as a work around: https://addons.mozilla.org/en-US/firefox/addon/mdn-anchors/

#17

I would love to have a quick way to jump to all the same levels as before, personally, but apparently very few people do this for some reason. Took me by surprise, but I don’t doubt the results of our testing, either.

I had planned on making an addon similar to what you did, so thank you for that. :slight_smile:

Sheppy

1 Like
#18

@freaktechnik - I noticed that your addon isn’t stripping out things like ?revision_saved=123456 from the URL. That results in SEO and other problems if these URLs get distributed. Any chance of a fix?

Thanks for this!

Sheppy

#19

Sure, I’ll try to get that done today, fixing some other projects first! Am I right in assuming that I can strip all get params?

#20

Yeah, they can all go (answering although I know you already fixed this). :slight_smile:

1 Like