Docs Spotlight: MDN Reference

Allison Reinheimer Moore -

The MDN docs are an amazing resource for folks developing for the web. Their HTML, CSS, and JavaScript reference docs are thorough, easy-to-understand, and highly discoverable. Let's dig into some of the choices they've made and why they work.

Page Structure

Screenshot from MDN's for…in reference with box highlighting the "In this article" outline.

Each reference page in MDN has the following structure:

  • Try it
  • Syntax
  • Description
  • Examples
  • Specifications
  • Browser compatibility
  • See also

At first glance, yes, they're all thing you'd expect to see in a docs page… but how often do you look at reference documentation where the first thing on the page, above the fold, is a runnable code example? I suspect the answer is "rarely", outside of MDN. This is a huge departure from the usual approach to reference docs and it is extremely effective at getting the user the info they need quickly.

For some reason, I struggle keeping the difference between the JS for…of and for…in loops straight in my head. I know that one is for properties of an object, while the other iterates through an iterable, but which one is which? 🤷‍♀️ A traditional reference page would lead with MDN's "Syntax" section.

Screenshot from the for…in reference from MDN, scrolled down to the "Syntax" section of the page.

The "Syntax" section provides the necessary information (if one takes the time to read it) and I could figure out my for…in vs. for…of problem with it… but the "Try it" section is so much better at quickly answering my question without having to parse through the prose.

Detail of the "Try it" runnable code example from MDN's for…in documentation.

At the end of the day, and it pains me to admit it, knowing how much reference documentation I've written over the years that people don't want to read, I'd much rather look at a runnable code snippet than read and understand a detailed parameter definition. I appreciate that the syntax detail is there (and there are situations where it will hold the answer to your question), but most of the time I just want the basic example. The MDN docs do a lot of other things well, but the way they've structured their reference, putting the runnable example before the detailed explanation, is what sets them so far apart from the competition.

Scorecard

For the sake of comparability, I've put together a series of criteria that I'll be using to assess the sites I write about.

❓Basic Question: What am I looking for when I go to this page?
➡️ An example of the syntax of the for…in loop in JavaScript.

  • Does the page have the info I’m looking for? Yes! ✅
  • Is all the info there? Yes! ✅
  • How far down the page is the info I want? It's at the top! ✅
  • How much do I need to scroll past to get there? Not at all! ✅
  • Is the first example a useful and fundamental case? Absolutely. ✅
  • How many times did I curse during this? 0
  • How many times did I make affirmative noises during this? 1, but I've looked at this page a lot.

Overall score: 5/5 and 1 smiley face 😀