From:  William Bamberg <wbamberg@mozilla.com>
Date:  08 Mar 2017 02:31:29 Hong Kong Time
Newsgroup:  news.mozilla.org/mozilla.dev.mdc
Subject:  

Re: Examples on top: JS pages

NNTP-Posting-Host:  63.245.214.181

Thanks for the feedback Stephanie!

On Tue, Mar 7, 2017 at 8:01 AM, Stephanie Hobson 
wrote:

> Sorry for jumping in with feedback late in the project...
>


After the user research this week, there will still be the opportunity to
change things. It is a bit late to make changes for the user testing, but
this is also my fault for implementing a new option so late :).



>
> I find the form fields are not obviously editable, I think they would
> benefit from looking more like form fields (same for the CSS). The styling
> on the Code Mirror homepage looks very editable to me.
>


Could you be a bit more specific about this? What is it about the Code
Mirror page that makes it look editable?



>
> v2
> I like this approach because it mimics a real debugging environment but
> would like to take it further... what about just having a single console
> 'window' where some stuff has already been typed? Like, just the bottom box
> with the examples from the top (including the comments).
>


Like this, you mean? http://imgur.com/a/3U27R

That's a very interesting idea. We'd want syntax highlighting, I think.



> We could even style it to look a bit more like a dev tools console.
>
>

> V2.2
> I don't understand how `exampleArray;` writes to the console and I think
> 'evaluate' is an intimidating term for a beginner. I liked the
> console.log() command used in V2 better. We should have the source and
> output in the same order if we're copying the interface between CSS and JS.
> I would move the CSS example under the CSS code.
>


This is all great feedback. The reason it doesn't use console.log is that
it's not really logging, just eval-ing the content. So I'd need to fake
console.log (which IIRC is what I did in v2). But I agree, it's better to
use console.log().



>
> Will, this is really neat. A lot of progress has been made in the last 7
> weeks! I really feel like both options address the #1 reason I will
> (guiltily!) click w3schools links sometimes.
>
>

Thanks! That's really nice to hear :). There's still a lot to do I think to
turn these from prototypes into real production pages.

Will



> Stephanie.
>
> On Mon, Mar 6, 2017 at 7:26 PM, William Bamberg 
> wrote:
>
>> So I finally managed to try out the option Sebastian described below (if I
>> have understood him correctly):
>>
>> https://developer.mozilla.org/en-US/docs/User:wbamberg/
>> Examples_on_top/Array.prototype.push():v2.2
>>
>> What do you think? (It's very much like the prototype CSS pages). Compared
>> with this:
>>
>> https://developer.mozilla.org/en-US/docs/User:wbamberg/
>> Examples_on_top/Array.prototype.push():v2
>>
>> and the original:
>>
>> https://developer.mozilla.org/en-US/docs/Web/JavaScript/
>> Reference/Global_Objects/Array/push
>>
>> Will
>>
>> On Thu, Jan 26, 2017 at 1:04 AM, Sebastian Zartner <
>> sebastianzartner@gmail.com> wrote:
>>
>> > Missed to send my last mail to the mailing list. So, for the others: My
>> > idea was to use an editor like for the CSS examples instead of the
>> command
>> > line. (see below)
>> >
>> > On 25 January 2017 at 23:30, William Bamberg 
>> wrote:
>> >
>> >> Hi Sebastian!
>> >>
>> >> So... is your suggestion to have an editor, with autocomplete, and a
>> >> button to "eval" that runs the contents of the editor, making it a
>> one-shot
>> >> operation like it is with CSS?
>> >>
>> >
>> > Yes.
>> >
>> >
>> >> I think this is problematic. For one thing, the autocomplete options
>> will
>> >> get big (e.g. array.map is going to take 4 lines of code, even if you
>> put
>> >> the map function in a single line).
>> >>
>> >
>> > The example for array.map could be put into two lines:
>> >
>> > var numbers = [1, 5, 10, 15];
>> > numbers.map(function(x){ return x * 2; });
>> >
>> > So, that takes much less vertical space than the console you have in
>> > https://developer.mozilla.org/en-US/docs/User:wbamberg/Examp
>> > les_on_top/Array.prototype.push():v2.
>> > Autocompletion could be provided when the text cursor is placed after
>> > numbers. and provide these options:
>> >
>> > map(function(x){ return x * 2; });
>> > map(Math.sqrt);
>> >
>> > For another, though, exploring a JS API seems more naturally a
>> multi-stage
>> >> process, so it seems much more natural to use a REPL model for JS, than
>> >> making you enter the whole thing and then eval it all. It means you can
>> >> play around, too, and see the result at each step:
>> >>
>> >>
>> >> *> var example = ["this"]*
>> >> *> example.push("thing")*
>> >>
>> >> *< 2*
>> >>
>> >> *> console.log(example)**< ["this", "thing"]*
>> >>
>> >> *> example.push("over", "there")**< 4*
>> >>
>> >> *> console.log(example)*
>> >> *< ["this", "thing", "over", there"]*
>>
>> >>
>> >> It feels important to be able to show intermediate results like this.
>> >>
>> >
>> > It would still be possible, as the user could enter the code line by
>> line.
>> > Though in the examples we want to show what a specific API does and the
>> > user should not have to care about other parts of the code like defining
>> > variables.
>> > In the example above all we want to show is what example.push("over",
>> > "there") does (add the items to the array and return the new length of
>> > the array).
>> >
>> > I've been thinking, though - if it's primarily vertical space that
>> bothers
>> >> you, why not use the example at the top as the instructions, instead
>> of an
>> >> almost-the-same duplicate? e.g. https://developer.mozilla.org/
>> >> en-US/docs/User:wbamberg/Examples_on_top/Array.prototype.push():v2.2 ?
>> >>
>> >> (also, I was thinking perhaps we could add a "play" button to the
>> >> console, that plays the example into it a character at a time, in case
>> you
>> >> just want to see the example being executed without having to type, or
>> in
>> >> case you need help figuring out what to do with the console?)
>> >>
>> >
>> > You're right, it doesn't make sense to have an almost-the-same
>> duplicate.
>> > That's why I actually expected to only have the interactive example
>> (which
>> > should be executed on page load to show the results without having to
>> click
>> > a button).
>> >
>> > Sebastian
>> >
>> >
>> >> On Wed, Jan 25, 2017 at 2:01 PM, Sebastian Zartner <
>> >> sebastianzartner@gmail.com> wrote:
>> >>
>> >>> On 25 January 2017 at 18:40, William Bamberg 
>> >>> wrote:
>> >>>
>> >>>> On Wed, Jan 25, 2017 at 12:25 AM, Sebastian Zartner <
>> >>>> sebastianzartner@gmail.com> wrote:
>> >>>>
>> >>>>> If we want to provide a way to try out the examples (and I do), I
>> >>>>> think the examples should be offered within a suggestions list like
>> in the
>> >>>>> CSS pages you created. This would save the space used for the
>> examples
>> >>>>> below the console.
>> >>>>>
>> >>>>
>> >>>> I think this is difficult for the JS examples in a way that it isn't
>> >>>> for CSS. The CSS examples are multiple-option, one-step (for the
>> most part,
>> >>>> anyway) - write any of these declarations, see the effect. Typically
>> the JS
>> >>>> examples are one-option, multiple-step: walking through a multi-step
>> >>>> process, and if you don't walk through all the same steps, you won't
>> see
>> >>>> the same result. Do A, then B, then C. If instead you do A, then G,
>> then C
>> >>>> won't make sense any more.
>> >>>>
>> >>>> So it's tricky. You could start by offering them A, then if that's
>> what
>> >>>> they enter, off them B, and so on. And if they don't enter the thing
>> you
>> >>>> expect, then? Just stop offering them suggestions, maybe? But I
>> think this
>> >>>> might also be confusing for the user, and seems like a very fussy UI
>> to
>> >>>> present.
>> >>>>
>> >>>
>> >>> Maybe there shouldn't be a single-line command line then but rather an
>> >>> editor like for CSS, so users don't have to enter each command
>> themselves
>> >>> but can play with the example code.
>> >>> This makes it more consistent with the CSS examples and provides a
>> >>> better UX.
>> >>>
>> >>> Sebastian
>> >>>
>> >>
>> >>
>> >
>> _______________________________________________
>> dev-mdc mailing list
>> dev-mdc@lists.mozilla.org
>> https://lists.mozilla.org/listinfo/dev-mdc
>> MDN contributor guide: http://bit.ly/ContributorGuide
>>
>
>