From:  Eric Shepherd <eshepherd@mozilla.com>
Date:  08 Mar 2017 00:25:27 Hong Kong Time
Newsgroup:  news.mozilla.org/mozilla.dev.mdc
Subject:  

Re: Examples on top: JS pages

NNTP-Posting-Host:  63.245.214.181

v2.2 is my favorite I’ve seen so far. I still prefer the way we already do it, personally, but I get that I’m a minority. If we’re decided on making a change to examples-on-top, this is the one I would pick.

I love this way of presenting the example bits though. I just still like the formal grammar better, because it’s more precise.

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


Eric Shepherd
Senior Technical Writer
Mozilla Developer Network 
Blog: https://www.bitstampede.com/
Twitter: https://twitter.com/sheppy