Getting interactive examples to MDN

“ This is scoped to become a pretty small change. ” – me, January 2017 .

Over the last year and a little bit, the MDN Web Docs group has been designing, building, and applying interactive examples for our reference web pages. The motivation for this was the concept that MDN should do more to help “ action-oriented” users: people who like to understand by seeing and playing around along with example code, rather than by reading through about it.

We’ ve just finished adding interactive illustrations for the JavaScript and CSS reference point pages. This post looks back in the project to see how we got right here and what we learned on the way.

First prototypes

The project was first outlined within the MDN item strategy , published at the end of 2016. We discussed some ideas on the MDN mailing list, and developed some prototypes.

The JS publisher looked like this:

The CSS editor looked like this:

We wanted the particular examples – especially the CSS examples – to show users the various kinds of syntax that an item can accept. In the early prototypes, we all did this using autocomplete. Once the user deleted the value assigned to some CSS property, we showed a good autocomplete popup listing different format variations:

First circular of user testing

In March 2017 Kadir Topal and I attended the first round associated with user testing, which was run simply by Mark Hurst . We learned a great deal regarding user testing, about our prototypes, and about what users wanted to notice. We learned that users wanted good examples and appreciated them being fast to find. Users liked interactive illustrations, too.

But autocomplete was not successful as a way to show various syntax forms. It just wasn’ t discoverable, and even people who do accidentally trigger it didn’ big t seem to understand what it was for.

Especially for CSS, though, all of us still wanted a way to show visitors the different kinds of syntax that an product could accept. For the CSS web pages, we already had a code obstruct in the pages that lists format options, like this:

 transform: matrix(1. 0, second . 0, 3. 0, 4. zero, 5. 0, 6. 0);
change: translate(12px, 50%);
transform: translateX(2em);
change: translateY(3in);
transform: scale(2, 0. 5);
transform: scaleX(2);
transform: scaleY(0. 5);
transform: rotate(0. 5turn);
transform: skew(30deg, 20deg);
 
 

One particular user interaction we saw, that individuals really liked, was when visitors would copy lines from this program code block into the editor, to see the impact. So we thought of combining this prevent with the editor.

With this next version, you can select a range from the block underneath, and the design is applied to the element over:

Looking back only at that prototype now, two things stick out: first, the basic interaction model that individuals would eventually ship was already in position. Second, although the changes we would create after this point were essentially regarding styling, they had a dramatic impact on the editor’ s usability.

Building a foundation

After that not much happened for a while, due to the fact our front-end developers were occupied on other projects. Stephanie Hobson helped improve the editor design, yet she was also engaged in a full-scale redesign of MDN’ s content pages. In June Schalk Neethling joined the team, dedicated to this particular project. He built a solid base for the editors and a whole new factor workflow. This would be the basis of the last implementation.

In this execution, interactive examples are maintained within the interactive-examples GitHub repository. Once a good interactive example is merged towards the repo, it is built automatically like a standalone web page which is then offered from the “ mdn. mozilla. net” domain. To include the example within an MDN page, we then add the interactive example’ s record using an iframe .

UX work and much more user testing

In late June, we showed the publishers to Jen Simmons and Dan Callahan , who provided us some very helpful feedback. The JavaScript editor appeared pretty good, but we were still having issues with the CSS editor. At this point this looked like this:

People didn’ t realize that they could edit the CSS, or perhaps that the left-hand side consisted of a listing of separate choices rather than a single prevent.

Stephanie and Schalk did a full UX review of each editors. We also had an self-employed UX review from Julia Lopez-Mobilia from The particular Brigade . After all this function, the editors looked like this within static screenshots:

Then we had another round associated with user testing. This time we happened to run remote user tests over video clip, with participants recruited through MDN itself. This gave us a good feedback loop for the editors: we’re able to quickly make and test modifications based on user feedback.

This time user testing was quite positive, and we decided we were looking forward to beta.

Beta tests

The beta check started at the end of August and survived for two weeks. We embedded publishers on three JavaScript and 3 CSS pages, added a study, and asked for feedback. Danielle Vincent mentioned it in the Mozilla Developer Newsletter , which drove thousands of people to our Discourse statement post .

Suggestions was overwhelmingly positive: 156/159 those who took the survey voted to find the editor on more pages, as well as the free-form text feedback was quite encouraging. We were confident that we a new good UX.

JavaScript examples and page load optimization

Now we had an publisher but very few actual examples. All of us asked Tag Boas to write illustrations for the JavaScript reference pages, and a couple of months he had written about 400 gorgeous concise examples.

See the example intended for Array. slice() .

There were another problem, though: the publishers regressed page load time too much. Schalk and Stephanie worked to shake every last millisecond of overall performance optimization out of the architecture, and finally, keep away from 2017, we decided to ship.

We have some extra tricks we all plan to implement this year to continue enhancing page load performance, the fact is we’ lso are still not happy with current overall performance on interactive pages.

CSS examples

Within the first three weeks of 2018, Schalk and I updated 400 JavaScript pages to include Mark’ s examples , and then we turned to getting good examples written for the CSS pages.

We requested help , Jen Simmons tweeted about it , and three weeks later our community acquired contributed more than 150 examples , with over a hundred coming from an one volunteer, mfluehr .

See the example for rotate3d() .

After that Rachel Andrew and Daniel Beck started dealing with us, and they took care of the remainder.

See the example for clip-path .

What’ s next?

Right now we’ re focusing on implementing interactive examples for the HTML reference . We have just finished a circular of user testing, with encouraging results , and hope to start writing good examples soon.

As I wish this post makes clear, this task has been shaped by many people adding a wide range of different skills. If you’ d like to help out with the task, please check out the interactive-examples repo as well as the MDN Talk forum , where we frequently announce updates.

Will is really a technical writer working on MDN.

A lot more articles by Will Bamberg…

If you liked Getting interactive examples to MDN by Will Bamberg Then you'll love Web Design Agency Miami