New MDN project: examples on top

[William Bamberg]

This email is to introduce a new MDN project, which to investigate whether
to restructure reference pages in MDN so syntax examples appear at the top
of the page.

*### The problem*

Although MDN is respected for completeness and correctness, it can be
harder for people to get a quick refresher of syntax using MDN than using
alternative sites like w3schools. For example:

http://www.w3schools.com/cssref/pr_background-color.asp - leads with an
example
https://developer.mozilla.org/en-US/docs/Web/CSS/background-color - leads
with some quite technical properties of this item

If all you want is a quick refresh of the syntax, w3schools is more useful
here.

So we're going to experiment with making reference pages start with a
simple example.


*### Some constraints*

* we'll experiment with JS, CSS, and Web API reference pages. Florian's
already started this by moving examples to the top in the JS Array pages:
https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array,
and we'll definitely make use of this.
* we'll not experiment with any other changes (e.g. live samples). This is
scoped to be a pretty small change.
* this might be a content-only change, or it might include some front-end
UI changes too, if we can find the resources.

*### The plan*

The basic plan is like this:

1. Prototype some designs: choose a few sample pages. For each sample page,
develop two or more prototype designs which have examples on top.
2. Qualitative tests: test prototype pages with web developers, revise in
response to feedback, and select the most effective designs.
3. A/B testing: apply the winning design to 50 or so pages in each domain
(JS, CSS, Web API) and run an A/B test with them on MDN.
4. Based on A/B tests, if the new page designs are more successful, update
all pages.

[Julien Sphinx]

Hello again :)

+1000 to this plan!
Reading the constraints, I was wondering: will any of the design make
use of simple live sample (the existing system) on top of articles?

Personnally, I've been thinking to try using the JSFiddleEmbed macro on
top (nothing concrete so far) to make live samples more "discoverable".

On the other hand, I can easily understand that we don't want readers to
get stuck at the top of the page interacting with the example…

Looking forward to this experiment :)

Respectfully,

Julien / Sphinx

> _______________________________________________
> dev-mdc mailing list
> dev...@lists.mozilla.org
> https://lists.mozilla.org/listinfo/dev-mdc
> MDN contributor guide: http://bit.ly/ContributorGuide

[William Bamberg]

Hi Julien!

Thanks for the answer, and happy new year to you.

> Reading the constraints, I was wondering: will any of the design make
> use of simple live sample (the existing system) on top of articles?

I'm not at all averse to this suggestion, and will look into it when trying
out some designs. I guess live samples will work better in some pages than
in others (e.g. APIs that need a lot of setup to see any result) but that's
not a reason not to use them in cases where they work well.

Will


On Tue, Jan 10, 2017 at 11:12 PM, Julien Sphinx <sphinx...@hotmail.fr>
wrote: