Examples on top: some proto-prototypes

[William Bamberg]

Hi dev-mdc!

I've been experimenting with some MDN pages for the "examples on top"
project[1].

A reminder: the idea at the moment is to come up with a few alternative
designs that we can test.

I have some initial prototype pages, and some questions. I'm interested in
people's thoughts on the questions, and also in ideas for more alternative
designs we could test.

I'm somewhat interested in opinions on how successful the initial
prototypes are, but I'd like us to try to be open-minded at this point,
since we are hoping to _test_ designs rather then just rely on opinions.

I'd also like to emphasise _prototype_ here. We're doing this to gauge
which designs are most likely to be effective. If we do decide to roll out
a redesign across 1000s of pages, we will need to invest in a good
technical solution for that design.

I'm for the moment keeping the things here: https://developer.mozilla.org/
en-US/docs/User:wbamberg/Examples_on_top.

At the moment I have 2 versions of a JS API page (Array.push()), and 6
versions of a CSS property page (border-top-color).

*## JS API*

For the Array.push() page I really just have one simple static example on
top. The only difference is in how I've presented the other examples.

In version 1 I just have a "More examples" link. I think this could use
better styling. I'm interested in ideas for how we could improve this
styling (I did try using .more-info .pull-aside () but it didn't really
work out very well. Something like that, though, seems like a good fit).

In version 2 I have the extra examples in a <details> element. One problem
with this approach is that the hidden examples appear in the ToC (which is
fine) but then clicking the links in the ToC doesn't work.

I thought about trying to make interactive examples for JS, but it was hard
to think of a good way to present it. I'd be happy to hear more ideas here.
I know Chris wrote a minimal JS console [3] for the learning area - maybe
we could use that? But it would be nice to be able to guide people through
the sample.

*## CSS property*

For the border-top-color page I have 6 examples, covering 2 dimensions.

The first dimension:
* is the example just a one-line sample usage
* or do we use the <pre> block at the start of the "Syntax" section [4]?

The second dimension: do we have
* a static example
* a "live sample" example using EmbedLiveSample, that links out to
Codepen/JSFiddle for interactivity
* an example that's playable in the page using EmbedGHLiveSample?

*## HTML elements*

I haven't done this one yet. I think we could have interactive designs,
like the ones proposed for CSS.


*## WebAPI*
I haven't done any of these. I think the difficulty is that the example is
either quite complex [5], or it is very similar to the <pre> at the start
of "Syntax" [6], which is already more or less at the top for these pages.
I'd welcome more ideas here.

Thanks!

Will

[1] https://groups.google.com/forum/#!topic/mozilla.dev.mdc/dhxwpNnlkSA
[2] https://developer.mozilla.org/en-US/docs/MDN/Contribute/Guid
elines/CSS_style_guide#.pull-aside
[3] https://developer.mozilla.org/en-US/docs/Learn/JavaScript/Fi
rst_steps/A_first_splash#Operators
[4] https://developer.mozilla.org/en-US/docs/Web/CSS/border-top-color#Syntax
[5] https://developer.mozilla.org/en-US/docs/Web/API/AudioContext/
createStereoPanner#Example
[6] https://developer.mozilla.org/en-US/docs/Web/API/AudioContext/
createStereoPanner#Syntax

[Sebastian Zartner]

Hello Will, hello everyone!

Thank you for creating those alternative pages, Will!
>From a first view, I like version 2 of the JS API alternatives and versions
2 and 6 of the CSS property alternatives.

Furthermore, here are a few quick unsorted thoughts on this topic:
Generally, I think playable examples are the best way to show what an API,
a property, an element, etc. can be used for. Those examples should be kept
minimal, though, i.e. they should not extend 10-15 lines of code.
For CSS properties, maybe the syntax examples (the <pre> block at the start
of the "Syntax" section) could be made available there, e.g. via a
suggestions list.

I also like the idea of providing the more advanced examples via a "More
examples" link.
As the syntax examples on CSS pages can be quite long, maybe they should
also be moved there to save some vertical space.
Or they could be put behind tabs, where each tab covers one group of
values. For example, the syntax examples for the mask property[1] would
then be split into "Keyword values", "Image values", "Combined values" and
"Global values".
If we have two dimensions of examples, we should probably have the
"Examples" headline above the live/interactive sample, or have the example
output above the code, like in version 6, to make a visual division between
the syntax examples and the live/interactive sample.

As I said, those ideas are not in a clean form yet. Once I thought more
about all that, I may have some clearer opinion.

Sebastian

[1] https://developer.mozilla.org/en-US/docs/Web/CSS/mask#Syntax

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

[Chris Mills]

> On 14 Jan 2017, at 19:47, Sebastian Zartner <sebastia...@gmail.com> wrote:
>
> Hello Will, hello everyone!
>
> Thank you for creating those alternative pages, Will!
> From a first view, I like version 2 of the JS API alternatives and versions
> 2 and 6 of the CSS property alternatives.

I prefer version 2 of the JS page too — I think having the wealth of more complex examples hidden behind the "more examples" link is really good, as it makes the page shorter and less daunting. We’ll obviously have to sort out the TOC discrepancy, but surely we can get a little tiny bit of FED help for this.

I am not sure what I prefer in terms of the CSS pages. I think any kind of simple up-the-top example is an improvement, but I also feel that the pages are still quite daunting. (The advanced details box and formal syntax stuff is scary to beginners and most people won’t need this that often.)

I think realistically the two things people will want the most are examples and browser compat data, so could we put those right up the top, and then have everything else following?

The advanced details and formal syntax stuff could perhaps be put under an “Advanced details” heading of some kind, and more in-depth examples could be put under a hidden section, like in the 2nd JS page.


Another thought - W3Schools has the examples hidden on separate pages. Do we like the sound of that, or should we keep the examples on the same page? I quite like the idea of having the advanced examples separated off onto standardized examples pages, with sandboxes, etc.

>
> Furthermore, here are a few quick unsorted thoughts on this topic:
> Generally, I think playable examples are the best way to show what an API,
> a property, an element, etc. can be used for. Those examples should be kept
> minimal, though, i.e. they should not extend 10-15 lines of code.

I also agree with this. Having a standard minimal editable example at the top of each page with an output pane would be really cool + useful.

> For CSS properties, maybe the syntax examples (the <pre> block at the start
> of the "Syntax" section) could be made available there, e.g. via a
> suggestions list.
>
> I also like the idea of providing the more advanced examples via a "More
> examples" link.

+1

> As the syntax examples on CSS pages can be quite long, maybe they should
> also be moved there to save some vertical space.
> Or they could be put behind tabs, where each tab covers one group of
> values. For example, the syntax examples for the mask property[1] would
> then be split into "Keyword values", "Image values", "Combined values" and
> "Global values”.

Hrm, a tabbed interface isn’t a bad idea for keeping space down. Maybe for advanced details, formal syntax, and those other scary details?

[William Bamberg]

On Mon, Jan 16, 2017 at 1:47 AM, Chris Mills <cmi...@mozilla.com> wrote:

>
> > On 14 Jan 2017, at 19:47, Sebastian Zartner <sebastia...@gmail.com>
> wrote:
> >
> > Hello Will, hello everyone!
> >
> > Thank you for creating those alternative pages, Will!
> > From a first view, I like version 2 of the JS API alternatives and
> versions
> > 2 and 6 of the CSS property alternatives.
>
> I prefer version 2 of the JS page too — I think having the wealth of more
> complex examples hidden behind the "more examples" link is really good, as
> it makes the page shorter and less daunting. We’ll obviously have to sort
> out the TOC discrepancy, but surely we can get a little tiny bit of FED
> help for this.
>
> I am not sure what I prefer in terms of the CSS pages. I think any kind of
> simple up-the-top example is an improvement, but I also feel that the pages
> are still quite daunting. (The advanced details box and formal syntax stuff
> is scary to beginners and most people won’t need this that often.)
>
> I think realistically the two things people will want the most are
> examples and browser compat data, so could we put those right up the top,
> and then have everything else following?
>
> The advanced details and formal syntax stuff could perhaps be put under an
> “Advanced details” heading of some kind, and more in-depth examples could
> be put under a hidden section, like in the 2nd JS page.

I agree that it's worth testing designs like this. We should be clear
though that this is extending the scope of this project, which was
originally focused on "examples on top". I think it's Kadir's call whether
this should in in scope. If it is I can prepare some designs that include
this option.

One extra point about moving compat tables to the top: possibly the real
wasteland for content is not the end of the page, but the middle. If compat
tables are at the end of the page, they're always in a known location and
the user can quickly get to them using "End" or Cmd+down arrow. If they are
near the top, but after examples, then the user needs to scroll (a variable
amount, depending on the size of the examples) to find them. But this is
speculation, and should be resolved through testing :).

Another related point: if people are used to finding compat tables at the
end, it may be a difficult adjustment for them if we move the tables. This
suggests that we should have usability regression tests for current MDN
users.

>
> Another thought - W3Schools has the examples hidden on separate pages.

The depends what you mean by "examples". They have static examples on the
same page, but link to a different page for the interactive version: "Try
it Yourself".

> Do we like the sound of that, or should we keep the examples on the same
> page? I quite like the idea of having the advanced examples separated off
> onto standardized examples pages, with sandboxes, etc.
>

Do you mean, keep all interactive examples on different pages, or just "the
advanced examples"? If the latter, what counts as an "advanced example"
(for CSS, say)? Currently we already have a lot of examples living on
separate pages (e.g.
https://developer.mozilla.org/en-US/docs/Web/CSS/transform#Examples).

>
> >
> > Furthermore, here are a few quick unsorted thoughts on this topic:
> > Generally, I think playable examples are the best way to show what an
> API,
> > a property, an element, etc. can be used for. Those examples should be
> kept
> > minimal, though, i.e. they should not extend 10-15 lines of code.
>
> I also agree with this. Having a standard minimal editable example at the
> top of each page with an output pane would be really cool + useful.
>

I'm a bit confused by this comment. Isn't that exactly what you have here:
https://developer.mozilla.org/en-US/docs/User:wbamberg/Examp
les_on_top/border-top-color_-_Version_6 ? So are you saying:

* "*this thing in variant 6 is* really cool and useful", or
* "*some other thing would be* really cool and useful"?

If the latter, what's the difference between what's shown in variant 6, and
the "some other thing"?

>
> > For CSS properties, maybe the syntax examples (the <pre> block at the
> start
> > of the "Syntax" section) could be made available there, e.g. via a
> > suggestions list.
> >
> > I also like the idea of providing the more advanced examples via a "More
> > examples" link.
>
> +1
>

> > As the syntax examples on CSS pages can be quite long, maybe they should
> > also be moved there to save some vertical space.
> > Or they could be put behind tabs, where each tab covers one group of
> > values. For example, the syntax examples for the mask property[1] would
> > then be split into "Keyword values", "Image values", "Combined values"
> and
> > "Global values”.
>
> Hrm, a tabbed interface isn’t a bad idea for keeping space down. Maybe for
> advanced details, formal syntax, and those other scary details?
>

This is starting to sound like a complete redesign of these pages.

If we want to do this, we need to get proper UX and front-end development
help to build these new examples. We'll not be testing anything in February.

Do we want to do this?

Will

[William Bamberg]

On Sat, Jan 14, 2017 at 11:47 AM, Sebastian Zartner <

sebastia...@gmail.com> wrote:

> Hello Will, hello everyone!
>
> Thank you for creating those alternative pages, Will!
> From a first view, I like version 2 of the JS API alternatives and
> versions 2 and 6 of the CSS property alternatives.
>

> Furthermore, here are a few quick unsorted thoughts on this topic:
> Generally, I think playable examples are the best way to show what an API,
> a property, an element, etc. can be used for. Those examples should be kept
> minimal, though, i.e. they should not extend 10-15 lines of code.

> For CSS properties, maybe the syntax examples (the <pre> block at the
> start of the "Syntax" section) could be made available there, e.g. via a
> suggestions list.
>
>

So version 6 is quite close to this, isn't it? It has a playable example
with the "syntax examples" just above, and you can copy/paste any of them
into the textbox and see the effect. It doesn't have autocomplete, which
would be nice, but otherwise it seems close.

> I also like the idea of providing the more advanced examples via a "More
> examples" link.

> As the syntax examples on CSS pages can be quite long, maybe they should
> also be moved there to save some vertical space.
>

Then are you suggesting that we should pick one (or possibly more) of
these, have them at the top, then keep the rest where they are and link to
them, like this:
https://developer.mozilla.org/en-US/docs/User:wbamberg/Examples_on_top/border-top-color_-_Version_7
?

Note that this is very much like the existing versions 1-3, with just the
addition of a "More examples" link. So is your suggestion essentially to
add this link to versions 1-3 (which sounds like a good idea!), or did you
have something else in mind?

Will

[William Bamberg]

Here's an example which (ab)uses the compat table macro to show a page with
tabs for "example syntax" and "interactive example":
https://developer.mozilla.org/en-US/docs/User:wbamberg/
Examples_on_top/border-top-color_-_Version_9. It isn't perfect by a long
way, but should give an idea.

On Mon, Jan 16, 2017 at 3:49 PM, William Bamberg <wbam...@mozilla.com>
wrote:

[Chris Mills]

> On 16 Jan 2017, at 21:53, William Bamberg <wbam...@mozilla.com> wrote:
>
>
>
> On Mon, Jan 16, 2017 at 1:47 AM, Chris Mills <cmi...@mozilla.com> wrote:
>

> > On 14 Jan 2017, at 19:47, Sebastian Zartner <sebastia...@gmail.com> wrote:
> >
> > Hello Will, hello everyone!
> >
> > Thank you for creating those alternative pages, Will!
> > From a first view, I like version 2 of the JS API alternatives and versions
> > 2 and 6 of the CSS property alternatives.
>

> I prefer version 2 of the JS page too — I think having the wealth of more complex examples hidden behind the "more examples" link is really good, as it makes the page shorter and less daunting. We’ll obviously have to sort out the TOC discrepancy, but surely we can get a little tiny bit of FED help for this.
>
> I am not sure what I prefer in terms of the CSS pages. I think any kind of simple up-the-top example is an improvement, but I also feel that the pages are still quite daunting. (The advanced details box and formal syntax stuff is scary to beginners and most people won’t need this that often.)
>
> I think realistically the two things people will want the most are examples and browser compat data, so could we put those right up the top, and then have everything else following?
>
> The advanced details and formal syntax stuff could perhaps be put under an “Advanced details” heading of some kind, and more in-depth examples could be put under a hidden section, like in the 2nd JS page.
>
>
> I agree that it's worth testing designs like this. We should be clear though that this is extending the scope of this project, which was originally focused on "examples on top". I think it's Kadir's call whether this should in in scope. If it is I can prepare some designs that include this option.
>
> One extra point about moving compat tables to the top: possibly the real wasteland for content is not the end of the page, but the middle. If compat tables are at the end of the page, they're always in a known location and the user can quickly get to them using "End" or Cmd+down arrow. If they are near the top, but after examples, then the user needs to scroll (a variable amount, depending on the size of the examples) to find them. But this is speculation, and should be resolved through testing :).
>
> Another related point: if people are used to finding compat tables at the end, it may be a difficult adjustment for them if we move the tables. This suggests that we should have usability regression tests for current MDN users.

This is a really good point well made, and definitely worth testing.

None of us want to suffer from premature speculation.

>
>
>
> Another thought - W3Schools has the examples hidden on separate pages.
>
>
> The depends what you mean by "examples". They have static examples on the same page, but link to a different page for the interactive version: "Try it Yourself".
>
>
> Do we like the sound of that, or should we keep the examples on the same page? I quite like the idea of having the advanced examples separated off onto standardized examples pages, with sandboxes, etc.
>
>
> Do you mean, keep all interactive examples on different pages, or just "the advanced examples"? If the latter, what counts as an "advanced example" (for CSS, say)? Currently we already have a lot of examples living on separate pages (e.g. https://developer.mozilla.org/en-US/docs/Web/CSS/transform#Examples).

Yeah, I was mainly talking about the Try it yourself stuff.

I know we do this quite a bit already, but I was mainly thinking about whether we should standardise it at some point in the future. Not necessarily as part of this current work ;-)

>
>
>
> >
> > Furthermore, here are a few quick unsorted thoughts on this topic:
> > Generally, I think playable examples are the best way to show what an API,
> > a property, an element, etc. can be used for. Those examples should be kept
> > minimal, though, i.e. they should not extend 10-15 lines of code.
>

> I also agree with this. Having a standard minimal editable example at the top of each page with an output pane would be really cool + useful.
>
>

> I'm a bit confused by this comment. Isn't that exactly what you have here: https://developer.mozilla.org/en-US/docs/User:wbamberg/Examples_on_top/border-top-color_-_Version_6 ? So are you saying:
>
> * "this thing in variant 6 is really cool and useful", or

Yes, I meant this one; sorry!

> * "some other thing would be really cool and useful"?

>
> If the latter, what's the difference between what's shown in variant 6, and the "some other thing"?
>
>

> > For CSS properties, maybe the syntax examples (the <pre> block at the start
> > of the "Syntax" section) could be made available there, e.g. via a
> > suggestions list.
> >

> > I also like the idea of providing the more advanced examples via a "More
> > examples" link.
>

> +1

>
> > As the syntax examples on CSS pages can be quite long, maybe they should
> > also be moved there to save some vertical space.

> > Or they could be put behind tabs, where each tab covers one group of
> > values. For example, the syntax examples for the mask property[1] would
> > then be split into "Keyword values", "Image values", "Combined values" and
> > "Global values”.
>
> Hrm, a tabbed interface isn’t a bad idea for keeping space down. Maybe for advanced details, formal syntax, and those other scary details?
>
>
> This is starting to sound like a complete redesign of these pages.
>
> If we want to do this, we need to get proper UX and front-end development help to build these new examples. We'll not be testing anything in February.
>
> Do we want to do this?

Again, I was just generally brainstorming about page redesign in general; I don’t necessarily mean we should do it all now.

I think we should keep the initial scope narrow and focus on that first. I’ll shush now ;-)

[Sebastian Zartner]

Forgive my late reply on this! Too busy lately.

On 17 January 2017 at 00:49, William Bamberg <wbam...@mozilla.com> wrote:
> On Sat, Jan 14, 2017 at 11:47 AM, Sebastian Zartner <sebastia...@gmail.com> wrote:

>> I also like the idea of providing the more advanced examples via a "More examples" link.

>> As the syntax examples on CSS pages can be quite long, maybe they should also be moved there to save some vertical space.
>

> Then are you suggesting that we should pick one (or possibly more) of these, have them at the top, then keep the rest where they are and link to them, like this: https://developer.mozilla.org/en-US/docs/User:wbamberg/Examples_on_top/border-top-color_-_Version_7 ?

>
> Note that this is very much like the existing versions 1-3, with just the addition of a "More examples" link. So is your suggestion essentially to add this link to versions 1-3 (which sounds like a good idea!),

Yes, the link in
https://developer.mozilla.org/en-US/docs/User:wbamberg/Examples_on_top/Array.prototype.push()_-_version_1
is good.

Sebastian