Re: JS page templates and topics (analysis)

Max: Does this work for your import? J

-------------------
Julee Burdekin
Content Strategist
Adobe Web Platform
@adobejulee
julee@adobe.com

From: Eliezer Bernart <eliezer.bernart@gmail.com<mailto:eliezer.bernart@gmail.com>>
Date: Tuesday, January 14, 2014 at 4:39 PM
To: Doug Schepers <schepers@w3.org<mailto:schepers@w3.org>>
Cc: Max Polk <maxpolk@gmail.com<mailto:maxpolk@gmail.com>>, julee <jburdeki@adobe.com<mailto:jburdeki@adobe.com>>, WebPlatform Public List <public-webplatform@w3.org<mailto:public-webplatform@w3.org>>
Subject: Re: JS page templates and topics (analysis)

Hello,

Today I merged the "JS Parameter" and the "JS Prototype" templates for the JS Object form.

As we discussed on the last conversations, and following the Doug's and Max suggestions, here are the new templates:

{{JS Syntax
|Format=
|Values=
}}

{{JS Syntax Parameter
|Name=
|Required=
|Description=
}}

I used composed templates to allow multiple values for Parameter, not sure if these are the best names for that. So, let me know if something should be changed. And here are the links to see the changes:

Example page:
http://docs.webplatform.org/test/javascript/Array

http://docs.webplatform.org/t/index.php?title=javascript/Array&action=formedit


Form page:
http://docs.webplatform.org/test/Form:JS_Object


Templates:
http://docs.webplatform.org/test/Template:JS_Syntax

http://docs.webplatform.org/test/Template:JS_Syntax_Parameter

http://docs.webplatform.org/test/Template:Syntax_Form_Section


It'll be great to have some feedback about the changes. Thanks!




Eliezer

@eliezerbernart
eliezerb


On Tue, Jan 7, 2014 at 5:48 AM, Doug Schepers <schepers@w3.org<mailto:schepers@w3.org>> wrote:
Hi, folks–

Sorry for the tardy response. I've been pondering this a bit. Here are some thoughts:

I agree that "Prototype" is too loaded a term there, but "Examples" is also loaded in the WPD context. I think that "Syntax" would be a good name for that section, and has analogs on other page types. What do you think?

Regardless of this issue, I think the templates and imports are good enough as-is to move to the main wiki. I'd like to get other opinions, and make the decision during Friday's meeting. If Max and Eliezer can attend then, that would be even better.

(FWIW, I don't think anything we do here will be irrevocable; we can take a little chance that we've made a mistake, and correct it later if we have. Making progress and getting closure is more important than perfection!)

Regards-
-Doug



On 12/30/13 10:35 AM, Max Polk wrote:
The parameter is ephemeral information.  What matters is the example
code.  For one example, there are zero, one, two, three, or whatever
parameters used with random names (arrayObj, size, element0, elementN,
etc):

Example:
     arrayObj = new Array([ element0 [, element1 [, ...[, elementN ]]]])
Parameter for above example:
     arrayObj (with description)
Parameter for above example:
     size (with description)
Parameter for above example:
     element0 ... elementN (with description)

To create a template for the above, it has to emphasize that it is an
example (a code form, an archetype, whatever you like), and zero or
more tag-along parameters following in its trail.  Would you prefer a
template named "Archetype" (meaning "a very typical example of a
certain person or thing")?  Then there is one "Format" parameter with
the typical way to use it, and zero or more parameter pairs named
Parm1Name & Parm1Desc, Parm2Name & Parm2Desc, etc?

If so, it would look something like:

{{Archetype
| Format=arrayObj = new Array([ element0 [, element1 [, ...[, elementN ]]]])
| Parm1Name=arrayObj
| Parm1Desc=Required. The variable name to which the '''Array'''
object is assigned.
| Parm2Name=size
| Parm2Desc=Optional. The size of the array. As arrays are zero-based,
created elements will have indexes from zero to size -1.
| Parm3Name=element0,...,elementN
| Parm3Desc=Optional. The elements to place in the array. This creates
an array with n + 1 elements, and a '''length''' of n + 1. Using this
syntax, you must supply more than one element.
}}

I know a variable number of parameters in a template is difficult but
we could use the: (pseudocode) "if Parm1Name render it along with
Parm1Desc; if Parm2Name render it along with Parm2Desc; etc" inside
the template for variable parameter expansion.

Are we getting closer to where we want to be?


On Fri, Dec 27, 2013 at 1:06 PM, Eliezer Bernart
<eliezer.bernart@gmail.com<mailto:eliezer.bernart@gmail.com>> wrote:
I agree! Prototype is a little bit confusing.

But I don't think that JS_Example will be a good name, since we have the
other examples...

A good solution for me it will be merge JS_Prototype with JS_Parameter, but
keep the JS_Parameter name.

{{JS Parameter Value
|Name=arrayObj
|Required=true
|Description=The variable name to which the '''Array''' object is assigned.
|Example=arrayObj = new Array()
}}

I made some updated on the Templates, and the Form in the last days Max, I
opened a Task on http://project.webplatform.org/msdnjs/issues/msjs-5.


If you don't mind in give a check to see if I'm in the way or if there is
something that I'm doing wrong. All my changes are being applied at
http://docs.webplatform.org/test/javascript/Array


What do you think?



Eliezer

@eliezerbernart
eliezerb


On Fri, Dec 27, 2013 at 3:51 PM, Max Polk <maxpolk@gmail.com<mailto:maxpolk@gmail.com>> wrote:

On 12/25/2013 11:06 PM, Eliezer Bernart wrote:

Prototype
* A basic sample of different prototypes to the object.


I have a change of heart.  It feels that we should not use the word
"Prototype" to describe examples at the top.  While the word "prototype" in
English means one thing, it has a very different meaning in JavaScript, and
we will cause confusion and lots of questions doing so.  Let us use another
word, perhaps Example.

Also, I feel we should merge JS_Protype and JS_Parameter since they
contextually are highly coupled  What would you think of this.

BEFORE (simple mediawiki text):

arrayObj = new Array()
arrayObj = new Array([ size ])
arrayObj = new Array([ element0 [, element1 [, ...[, elementN ]]]])

arrayObj: Required. The variable name to which the '''Array''' object is
assigned.
size: Optional. The size of the array. As arrays are zero-based, created
elements will have indexes from zero to size -1.
element0,...,elementN: Optional. The elements to place in the array. This
creates an array with n + 1 elements, and a '''length''' of n + 1. Using
this syntax, you must supply more than one element.

AFTER (three examples, each with their independent set of parameters):

{{JS_Example
| Example=arrayObj = new Array()
| Parameter1=arrayObj: Required. The variable name to which the
'''Array''' object is assigned.
}}

{{JS_Example
| Example=arrayObj = new Array([ size ])
| Parameter1=arrayObj: Required. The variable name to which the
'''Array''' object is assigned.
| Parameter2=size: Optional. The size of the array. As arrays are
zero-based, created elements will have indexes from zero to size -1.
}}

{{JS_Example
| Example=arrayObj = new Array([ element0 [, element1 [, ...[, elementN
]]]])
| Parameter1=arrayObj: Required. The variable name to which the
'''Array''' object is assigned.
| Parameter2=size: Optional. The size of the array. As arrays are
zero-based, created elements will have indexes from zero to size -1.
| Parameter3=element0,...,elementN: Optional. The elements to place in the
array. This creates an array with n + 1 elements, and a '''length''' of n +
1. Using this syntax, you must supply more than one element.
}}

Some duplication, but since it's highly coupled, it makes it easier to add
examples as independent units.  Like?  Dislike?