Bringing Interactive Examples to MDN

By | March 20, 2018

This is scoped to be a reasonably small change. me, January 2017.

Over the final yr and a bit, the MDN Net Docs crew has been designing, constructing, and implementing interactive examples for our reference pages. The motivation for this was the concept MDN ought to do extra to assist action-oriented customers: individuals who prefer to study by seeing and taking half in round with instance code, quite than by studying about it.

Weve simply completed including interactive examples for the JavaScript and CSS reference pages. This submit appears again on the undertaking to see how we acquired right here and what we discovered on the way.

First prototypes

The undertaking was first outlined within the MDN product strategy, revealed on the finish of 2016. We mentioned some concepts on the MDN mailing listing, and developed some prototypes.

The JS editor regarded like this:

Early prototype of JavaScript editor

The CSS editor regarded like this:

Screenshot of CSS editor after first consumer testing

We needed the examples particularly the CSS examples to indicate customers different sorts of syntax that an merchandise may settle for. Within the early prototypes, we did this utilizing autocomplete. When the consumer deleted the worth assigned to a CSS property, we confirmed an autocomplete popup itemizing different syntax variations:

First spherical of consumer testing

In March 2017 Kadir Topal and I attended the primary spherical of consumer testing, which was run by Mark Hurst. We discovered an incredible deal about consumer testing, about our prototypes, and about what customers needed to see. We discovered that customers needed examples and appreciated them being fast to search out. Customers appreciated interactive examples, too.

But autocomplete was not profitable as a approach to present different syntax types. It simply wasnt discoverable, and even individuals who did by accident set off it didnt appear to grasp what it was for.

Especially for CSS, although, we nonetheless needed a approach to present readers different sorts of syntax that an merchandise may settle for. For the CSS pages, we already had a code block within the pages that lists syntax choices, like this:

transform: matrix(1.0, 2.0, 3.0, 4.0, 5.0, 6.0);transform: translate(12px, 50%);transform: translateX(2em);transform: translateY(3in);transform: scale(2, 0.5);transform: scaleX(2);transform: scaleY(0.5);transform: rotate(0.5turn);transform: skew(30deg, 20deg);

One consumer interplay we noticed, that we actually appreciated, was when readers would copy strains from this code block into the editor, to see the impact. So we considered combining this block with the editor.

In this subsequent model, you probably can choose a line from the block beneath, and the fashion is utilized to the ingredient above:

Looking again at this prototype now, two issues stand out: first, the essential interplay mannequin that we might finally ship was already in place. Second, though the changes we might make after this level have been primarily about styling, they’d a dramatic impact on the editors usability.

Building a foundation

After that not a lot occurred for some time, as a outcome of our front-end builders have been busy on different initiatives. Stephanie Hobson helped enhance the editor design, however she was additionally engaged in a full-scale redesign of MDNs article pages. In June Schalk Neethling joined the crew, devoted to this undertaking. He constructed a stable basis for the editors and a complete new contribution workflow. This may be the idea of the ultimate implementation.

In this implementation, interactive examples are maintained within the interactive-examples GitHub repository. As quickly as an interactive instance is merged to the repo, it’s constructed routinely as a standalone net web page which is then served from the area. To incorporate the instance in an MDN web page, we then embed the interactive examples doc utilizing an iframe.

UX work and extra consumer testing

At the top of June, we confirmed the editors to Jen Simmons and Dan Callahan, who supplied us some very helpful suggestions. The JavaScript editor appeared fairly good, however we have been nonetheless having issues with the CSS editor. At this level it regarded like this:

Early prototype of CSS editor in June 2017

People didnt perceive that they may edit the CSS, and even that the left-hand aspect consisted of a listing of separate decisions quite than a single block.

Stephanie and Schalk did a full UX overview of each editors. We additionally had an unbiased UX overview from Julia Lopez-Mobilia from The Brigade. In any case this work, the editors regarded like this in static screenshots:

JS editor for the ultimate consumer test

CSS editor for the ultimate consumer test

Then we had one other spherical of consumer testing. This time we ran distant consumer exams over video, with contributors recruited by means of MDN itself. This gave us a good suggestions loop for the editors: we may shortly make and take a look at changes primarily based on consumer feedback.

This time consumer testing was very optimistic, and we determined we have been prepared for beta.

Beta testing

The beta take a look at began on the finish of August and lasted for 2 weeks. We embedded editors on three JavaScript and three CSS pages, added a survey, and requested for suggestions. Danielle Vincent mentioned it within the Mozilla Developer Newsletter, which drove 1000’s of individuals to our Discourse announcement post.

Feedback was overwhelmingly optimistic: 156/159 individuals who took the survey voted to see the editor on extra pages, and the free-form textual content suggestions was very encouraging. We have been assured that we had a good UX.

JavaScript examples and web page load optimization

Now we had an editor however only a few precise examples. We requested Mark Boas to write down examples for the JavaScript reference pages, and in a few months he had written about four hundred lovely concise examples.

See the instance for Array.slice().

We had one other drawback, although: the editors regressed web page load time an extreme quantity of. Schalk and Stephanie labored to wring each final millisecond of efficiency optimization out of the structure, and eventually, in December 2017, we determined to ship.

We have some additional tips we plan to implement this yr to proceed enhancing web page load efficiency, the very fact is have been nonetheless not proud of present efficiency on interactive pages.

CSS examples

In the primary three weeks of 2018, Schalk and I up to date four hundred JavaScript pages to include Marks examples, after which we turned to getting examples written for the CSS pages.

We requested for help, Jen Simmons tweeted about it, and three weeks later our neighborhood had contributed greater than one hundred fifty examples, with over 100 coming from a single volunteer, mfluehr.

See the instance for rotate3d().

After that Rachel Andrew and Daniel Beck began working with us, and so they took care of the rest.

See the instance for clip-path.

Whats next?

Right now have been engaged on implementing interactive examples for the HTML reference. We’ve got simply completed a spherical of consumer testing, with encouraging results, and hope to begin out writing examples soon.

As I hope this submit makes clear, this undertaking has been formed by many individuals contributing a variety of various expertise. If youd like to assist out with the undertaking, please take a glance at the interactive-examples repo and the MDN Discourse forum, the place we usually announce updates.

Will is a technical author engaged on MDN.

More articles by Will Bamberg

Please check this great service at: or visit FREE SERVICES menu
[Total: 0    Average: 0/5]

Leave a Reply

Your email address will not be published. Required fields are marked *

This site uses Akismet to reduce spam. Learn how your comment data is processed.