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

Re: Examples on top: JS pages

NNTP-Posting-Host:  63.245.214.181

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
>>>
>>
>>
>