The future of examples on MDN

MDN
#1

We need to have a discussion about how we’re going to handle examples going forward. We have several ways to present examples and their output, some of which are useful for very specific use cases and others which are more generally useful. All of them have issues that make them a non-starter as a one-size-fits-all solution for example presentation.

At the most basic level, when just throwing a few lines of code into the page, with no intent to show any output or the like, we can just use a <pre> block. That’s fine and works reasonably well (although the feature to highlight specific lines of code needs to be exposed to the UI somehow, ideally).

Common forms of example

Things get much more complicated when you have larger examples that you want to present output for. There are a few use cases here. I’ll present the ones I can think of and the issues that will affect our decision-making as to a long-term solution for example presentation.

Short, interactive, syntax demonstration snippets

This is the kind of short example that shows how to use a feature at a fairly fundamental level. What do the different parameters do? What affect do these different values have on a CSS property? That kind of thing.

These need to have an inline editor, need to show all of the code involved, and need to provide immediate presentation of the effect of changes the reader makes to the example code. They don’t need to show more than one language, and generally only need to deal with examples under 15 lines long or so.

Example: CSS transform property

Large, monolithic examples

These are longer, more involved examples, possibly including any combination of CSS, JavaScript, and HTML. Each language’s code is presented in one long <pre> block. The output of the code is also presented. There is not necessarily any editing support (currently not, but there’s no reason not to allow it in the future if so desired).

Example: Lighting in WebGL (this is actually a segmented example, but it uses very large chunks of code instead of small ones, so it’s close enough)

Large, segmented examples

These are similar to the monolithic examples, in that they are longer examples and may include any combination of the three major languages. However, the code may be broken into smaller chunks for easier reading and to allow explanatory text to be interspersed among the sections of code. These, too, don’t currently require editing support but could in the future if so desired.

Example: Timing element visibility with the Intersection Observer API

Step-by-step or related examples

These examples are monolithic or segmented examples, except there are a series of them throughout the same article. In the case of a step-by-step example, an article may have a number of sections, each of which presents an example which builds on the code from the previous example. For instance, the first section may show how to initialize a WebGL context. The second section might add code to clear it to a specific color. The third might demonstrate drawing a box. The next section might add textures. And so forth. Each section requires code from the previous section and builds upon it. Currently, we have to actually repeat the shared code (possibly hidden using CSS, but still repeated).

Related examples may not build on each other, but might share the same CSS, for example. Here, too, we have to repeat the shared code.

Repeating code bloats the page, slowing load times. It also, perhaps more importantly, means that the writers have to remember to make changes in multiple places in order to fix bugs or make improvements to code that’s shared, rather than only having to change one place.

Tools

These are essentially monolithic examples, except the code is not displayed to the user. For example, the MDN CSS color picker tool.

Our current example presentations

We have several ways to present examples at present:

  • Simple inline blocks for each language, with {{EmbedLiveSample}} if we wish to show the output
  • Zero or more <pre> blocks for any combination of the languages, along with {{EmbedLiveSample}} to assemble all of the code blocks together and show the results in an <iframe>
  • Example on GitHub and {{EmbedGHLiveSample}} (doesn’t show the code, just the result though)
  • Example on GitHub and {{EmbedInteractiveExample}} (shows the code in an editable widget, with live refreshes of the result)

The interactive example editor by design supports only short and simple snippets, and only supports a single language (CSS, JavaScript, or HTML). It doesn’t really handle larger examples, and isn’t currently ready to be used more than once on a page.

The older, so-called live sample mechanism, lets us present multiple chunks of code and assemble them into a visual representation of the output, which is great. However, it doesn’t allow editing and experimenting with the code (aside from providing links to CodePen and JSFiddle). It also doesn’t support sharing of code among examples; currently, we instead have to duplicate the common code and use the “hidden” class on it if we don’t want to see it.

What’s the plan?

We need a long-term plan for examples on MDN. The interactive example editor is amazing but isn’t (at least at this time) capable of handling all the use cases for examples.

We need to make some decisions.

  • Do we enhance the interactive example editor to cover the other use cases it doesn’t support now?
  • Do we discard the current live sample system and replace it with a new mechanism that lives side-by-side with the interactive examples?
  • Do we find ways to improve the existing live sample system to correct some of its deficiencies?
  • Do we drop some of our use cases entirely?

I expect there are some strong opinions on this. I know I have them, anyway. I will share my personal thoughts in my next post.

Sheppy

#2

A few thoughts of my own. I’m sure I have more, but this will be a starting point.

First: I love the interactive example editor, as a reader. It’s very slick and convenient.

With that taken care of, let’s get into my thoughts on the future. :slight_smile:

I definitely agree that the old “live sample” system is flawed and needs to be overhauled or replaced. I don’t know which will make the most sense once the requirements are nailed down.

The main problems I see with the live sample system are:

  • Lack of a way to reuse code blocks in multiple examples
  • No UI for highlighting lines within the example code
  • Lack of a mechanism for reviews and validation
  • Writing code in an editor not specifically designed for code editing is awful

I know we’ve been moving toward using GitHub more and more. Everyone knows I’m not entirely happy about it, for various reasons. I do not really want to see all examples move to GitHub. The resulting time gap between updating article content and the changed code appearing is a large problem, leading to a period of time during which the text and code are not in sync, potentially confusing readers.

I also have never been a fan of having to break context in order to write. Having to leave MDN to work on samples bothers me enormously.

My ideal solution would involve using GitHub as a back-end but doing all the work right on MDN, with a sample editor that “saves” your work to a GitHub repository, with UX for submitting for review, etc. I’d also like to have it so that code goes live right away, at least for trusted contributors, but possibly with a mechanism in place to indicate that it’s unvalidated code.

The trick is the code reuse issue – finding a way to allow a sample to import a piece of code created in another example is IMHO a crucial component of any solution we find.

I have more thoughts bouncing around my skull but can’t get them all out right now. I’ll probably add more later. :slight_smile:

Sheppy

#3

This is a difficult issue to get my head around. I definitely agree that there is an issue, but it really needs some detailed exploration and thinking. In short, I’m glad you started this thread!

I don’t think there is a one-size-fits all solution. I think there are different use cases that require different tools. To me, the main categories are:

  1. Add a quick example to a page easily. The existing live sample macro does this well. Without this, and when faced with a more intimidating solution such as GitHub or interactive examples, casual contributors who want to add a quick example to a page will likely not do so.

  2. Add a thorough, in-depth example to a page.

  3. Add interactive examples to the page.

2 and 3 are more likely to be done by MDN staff, and less likely to be done by volunteers. I actually think 2 and 3 could be the same solution, but 1 can’t be. 1. Needs to be really simple, achievable just on the page, without a big backend or other dependencies attached to it. We could monitor what’s added, and turn worthy examples into GitHub examples.

I reckon the GH macro could be the best solution to extend, and I agree with a lot of what you’ve said about it. We’d have to turn it into some kind of system whereby:

  1. You write the files in a certain structure each time, the same for each github repo (or directory perhaps), perhaps with a config file if needed.
  2. You can then embed the example on the page by referencing it’s specific github repo/directory, maybe even referencing the HTML index page of the example. This means you could have multiple examples in the same directory that share some of the same files.
  3. You can also choose to embed the code files in the page, so the source can be shown alongside the live sample, by including certain parameters in the macro.
  4. If you don’t want to show the entirety of each file in the published page, maybe you could have a syntax that allows you to show only a certain chunk of code, e.g. lines 23-53.
  5. The example source should be editable from within MDN’s edit view. For an example to be edited, the user would need a github account. We’d need our system to turn their edit into a pull request that we can then review. The workflow here would need some serious consideration — what do we show on the page/edit view when an example is in the middle of being edited and a PR is open?

And of course we need to expose the line highlighting functionality to the editor UI. That is a long standing pain.

#4

In general terms, I agree with you, Chris.

I also specifically agree that there needs to be a way to present subsets of the source code, instead of just slamming the whole thing into the page. There are a few ways this can be done. Ideally, I think, all of these would be available.

  • By line number(s), as you already mentioned. The drawback here is that if the code is updated, the text has to change too, just to fix the line numbers.
  • By function name (for JavaScript), selector (for CSS), or ID (for HTML), to pull just the relevant content from the source.
  • By using marker comments, such as:
...

// {{section-begin: initialize}}

if (!init_webgl()) {
  show_error("Unable to start WebGL.")}}
  exit(1);
}

// {{section-end: initialize}}

...

Then you could use a macro in your article like this (the syntax of course is up for debate):

{{EmbedGHSourceSection("samplename", "filename.js", "initialize")}}

This would embed into the article the snippet of code between the section-begin and section-end markers, given the specified name (“initialize”). The highlighter can be determined from the file’s extension (".js" in this case).

Sheppy

#5

I think using some kind of markers is a great idea, however it isn’t great in terms of backwards compatibility with existing demos.

I reckon we’d need to allow people use either line numbers or markers, to provide flexibility in approach, and a lower barrier to entry. Again, putting these markers into the code is more complex, and contributors would be less likely to do it.

If code changes, you may still have to update the markers and text.

#6

Oh, I agree, both approaches should be available.

#7

I’m recording this here as another idea that would be nice to have in an update to live code examples:

“Show solution” button in Active learning examples should toggle displaying of the solution code while preserving user edits — https://bugzilla.mozilla.org/show_bug.cgi?id=1425649