Examples on top: revising after user research

[William Bamberg]

Hi dev-mdc!

Stephanie and I have been working on revising the new pages in response to
the user research we did (
https://docs.google.com/document/d/1yrNKnDiWiOdqL5gkYipDN-wesbDq4k0vaGT3nR8Jd3w/edit#heading=h.52naqxph116k
).

We've now updated all the "Prototype" links at
https://developer.mozilla.org/en-US/docs/User:wbamberg/Examples_on_top with
revised pages.

I haven't yet removed autocomplete but still intend to do this.

I kept the old pages around in case you want to so a side-by-side
comparison, e.g.

new:
https://mdn.github.io/js-examples/editable-samples/pages/array-push-2/
old:
https://mdn.github.io/js-examples/editable-samples/pages/array-push-2/index-old.html

new:
https://mdn.github.io/css-examples/editable-samples/pages/filter/
old:
https://mdn.github.io/css-examples/editable-samples/pages/filter/index-old.html

There are still a few more things to do, but this is basically what we're
proposing to go with for the A/B tests.

I should respond to one comment that was made in the summary doc: it was
suggested that we could fix people not knowing that the box was editable by
labelling it. Unfortunately, I don't think people read anything, and are
more likely to rely on cues like the styling of the boxes to decide whether
it's inviting you to edit. Also, this wasn't a *huge* problem in the tests:
most people did actually successfully edit stuff. It was autocomplete that
was really not usable.

Will

[Kadir Topal]

Thanks Stephanie and Will for your work on this. The new prototypes look great *and* they address the issues seen in the test :) can’t wait to see them in action.

> Am 17.03.2017 um 00:37 schrieb William Bamberg <wbam...@mozilla.com>:
>
> Hi dev-mdc!
>
> Stephanie and I have been working on revising the new pages in response to
> the user research we did (
> https://docs.google.com/document/d/1yrNKnDiWiOdqL5gkYipDN-wesbDq4k0vaGT3nR8Jd3w/edit#heading=h.52naqxph116k
> ).
>
> We've now updated all the "Prototype" links at
> https://developer.mozilla.org/en-US/docs/User:wbamberg/Examples_on_top with
> revised pages.
>
> I haven't yet removed autocomplete but still intend to do this.

> [..]

>
> There are still a few more things to do, but this is basically what we're
> proposing to go with for the A/B tests.
>
> I should respond to one comment that was made in the summary doc: it was
> suggested that we could fix people not knowing that the box was editable by
> labelling it. Unfortunately, I don't think people read anything, and are
> more likely to rely on cues like the styling of the boxes to decide whether
> it's inviting you to edit. Also, this wasn't a *huge* problem in the tests:
> most people did actually successfully edit stuff. It was autocomplete that
> was really not usable.

I think this is spot on. Contextual cues are much better than expecting people to pick up on the labeling. It seems that people scan more than they read when they’re looking for information.

—Kadir

[Sebastian Zartner]

Jumping in late again. I hope it's not too late to give some feedback on this!

On 17 March 2017 at 18:28, Kadir Topal <ato...@mozilla.com> wrote:
> Thanks Stephanie and Will for your work on this. The new prototypes look great *and* they address the issues seen in the test :) can’t wait to see them in action.

+1

>> Am 17.03.2017 um 00:37 schrieb William Bamberg <wbam...@mozilla.com>:
>> I haven't yet removed autocomplete but still intend to do this.

I think the autocompletion just needs to be revised in order to be
successful. Currently, it's only shown in very specific occasions,
i.e. when you place the text cursor right after the dot on the JS
pages. On the CSS pages I couldn't get the popup to display at all. I
remember this has worked before. Also, on some CSS pages the
CodeMirror instance doesn't work at all due to a JavaScript error. So,
in both cases they are broken.

Instead of removing the autocompletion you should make it more
present. I.e. the popup should open and stay open whenever you
navigate within the function name of a JS API. E.g. in case of the
Array.prototype.slice() page this means the popup should be shown when
the caret is placed anywhere within the word 'slice'. For CSS
properties the popup should always be shown whenever the caret is
placed at the right side of the colon, independent of whether there is
a value or not.
And in both cases the popup should also appear immediately when you
click the Edit button. Furthermore, when you previously dismissed the
popup by pressing Escape, you should be able to display it again by
pressing Ctrl+Space like in an IDE.

>> I should respond to one comment that was made in the summary doc: it was
>> suggested that we could fix people not knowing that the box was editable by
>> labelling it. Unfortunately, I don't think people read anything, and are
>> more likely to rely on cues like the styling of the boxes to decide whether
>> it's inviting you to edit. Also, this wasn't a *huge* problem in the tests:
>> most people did actually successfully edit stuff.
>

> I think this is spot on. Contextual cues are much better than expecting people to pick up on the labeling. It seems that people scan more than they read when they’re looking for information.

I think one issue is also that when you click the Edit button the
value is selected but there is no blinking caret to indicate that the
text is editable.
I saw that you removed the syntax highlighting from the code of some
pages. Did you do that to indicate that they are editable?

You're right that people don't read, though I still believe a simple
"Try and edit the code below:" or something similar would be read by
some at least. The label could also be placed inside the
autocompletion popup saying something like "Edit the value or choose
and example".

Sebastian

[Eric Shepherd]

I still don’t understand what the Edit button is supposed to accomplish. It seems to just highlight a few words and empty the contents of the output box. Why? It’s puzzling.

I also agree we still need a label or heading on these boxes.

> On Apr 2, 2017, at 5:37 PM, Sebastian Zartner <sebastia...@gmail.com> wrote:
>
> I think one issue is also that when you click the Edit button the
> value is selected but there is no blinking caret to indicate that the
> text is editable.
> I saw that you removed the syntax highlighting from the code of some
> pages. Did you do that to indicate that they are editable?
>
> You're right that people don't read, though I still believe a simple
> "Try and edit the code below:" or something similar would be read by
> some at least. The label could also be placed inside the
> autocompletion popup saying something like "Edit the value or choose
> and example".
>

Eric Shepherd
Senior Technical Writer
Mozilla Developer Network <https://developer.mozilla.org/>
Blog: https://www.bitstampede.com/
Twitter: https://twitter.com/sheppy