Re: IA of Max's JS files for upload?

Thanks, PhistucK! Responses inline, below. J


----------------------------
julee@adobe.com
@adobejulee

From: PhistucK <phistuck@gmail.com<mailto:phistuck@gmail.com>>
Date: Wednesday, June 12, 2013 12:43 PM
To: julee <jburdeki@adobe.com<mailto:jburdeki@adobe.com>>
Cc: Scott Rowe <scottrowe@google.com<mailto:scottrowe@google.com>>, Chris Mills <cmills@w3.org<mailto:cmills@w3.org>>, Webplatform mailing list <public-webplatform@w3.org<mailto:public-webplatform@w3.org>>, Doug Schepers <schepers@w3.org<mailto:schepers@w3.org>>, Max Polk <maxpolk@gmail.com<mailto:maxpolk@gmail.com>>
Subject: Re: IA of Max's JS files for upload?

See my comments inline.


☆PhistucK


On Wed, Jun 12, 2013 at 4:02 AM, Julee Burdekin <jburdeki@adobe.com<mailto:jburdeki@adobe.com>> wrote:
Scott & Chris:

As far as information architecture goes, do either of you want to review and comment on the naming structures before Max uploads his first batch?[1][2]

For instance, a couple of things I'm noticing:

 *   Node is called "Objects" instead of "Object"

Where do you see that? perhaps I am misunderstanding.​​
On the output pages:

http://dev.maxpolk.org/msdnjs/index.php?title=Special:AllPages&from=Constants&to=Objects%2Farguments


 *   Max is using initial caps, where our convention is to use lowercase unless required. So, operator, statements, constants, etc., should all be lower case, no?

I do not recall a lower case policy.​​ Everything is named according to its usage in the language/bindings. For case insensitive (or somewhat insensitive, anyway) languages, like HTML or CSS we do prefer lower case.
Are you referring to "Array" versus "array"? or to "Function" versus "function" (within the title of the page)?
The former should stay "Array" (this is the actual way to use it), the latter should be dropped anyway, so no need to convert anything, in my opinion.

Not Array, not keywords, etc.. The parent node that buckets the objects, functions, or whatever.

 *   Operator pages are named in plain English (i.e.: Operators/Division Assignment<http://dev.maxpolk.org/msdnjs/Operators/Division_Assignment> instead of using "/="), which makes sense, but should we align this with the at rules in CSS (i.e.: wiki/css/atrules/@media)?

​That is weird. I prefer the actual syntax rather than the plain English name.​ But I do not feel that strongly about it.



Thanks.

Julee

[1] http://dev.maxpolk.org/msdnjs/index.php?title=Special:AllPages&from=Constants&to=Objects%2Farguments

[2] http://dev.maxpolk.org/msdnjs/index.php?title=Special%3AAllPages&from=Objects%2Farguments&to=&namespace=0


----------------------------
julee@adobe.com<mailto:julee@adobe.com>
@adobejulee




-----Original Message-----
From: Max Polk <maxpolk@gmail.com<mailto:maxpolk@gmail.com>>
Date: Tuesday, June 11, 2013<tel:2013> 4:28 PM
To: Doug Schepers <schepers@w3.org<mailto:schepers@w3.org>>
Cc: Webplatform mailing list <public-webplatform@w3.org<mailto:public-webplatform@w3.org>>
Subject: Re: First full upload of MSDN-contributed JavaScript pages
Resent-From: <public-webplatform@w3.org<mailto:public-webplatform@w3.org>>
Resent-Date: Tuesday, June 11, 2013<tel:2013> 4:29 PM

The methodology is explained in the Strategy section of my notes page:

    http://dev.maxpolk.org/msdnjs/MSDN-JS_development


Basically I'm using the original structure:

    https://github.com/webplatform/msdn-js/blob/master/js_toc.html


And simplifying page names to avoid duplication.  I first said a bit
about it here:

    http://lists.w3.org/Archives/Public/public-webplatform/2013May/0261.html


And you can see PhistucK's response, where a modification was
suggested.  I was focused mainly on getting something out there so far
and didn't address renaming things yet.  The scripts used are public
at:

    https://github.com/maxpolk/msdn-js-conversion


And it's a Bash script that uses Linux tools for fixing filename
anomalies, fixing internal links, renaming pages, removing unusual UTF
characters, doing the page to final location mapping, calling the
Python conversion script to actually convert the HTML into Mediawiki
markup with proper escaping, and afterward uploading everything to the
right location using a modified wpd tool.

Page names are a bit tricky.  Some functions (isArray) are not called
on objects, but on the prototype, such as Array.isArray(x), so its
page name is "Objects/Array/Array.isArray Function".  This differs
from the normal page name for functions called on instances like
x.concat(b, c) with page name "Objects/Array/concat Method."

We already have some good candidates for naming improvements from this
untouched original structure by PhistucK, and as long as there is a
deterministic process to arrive at the right name, it can be coded to
use that.  I have no preference as to final structure at the moment,
so whatever is desired I'm here to make it happen.

On Mon, Jun 10, 2013<tel:2013> at 2:49 AM, Doug Schepers <schepers@w3.org<mailto:schepers@w3.org>> wrote:
Hi, Max-

Great work!

This is an excellent first pass. Can you talk a bit about your methodology,
and maybe point us to your import script?

We'll need to get serious about discussing how we want the pages to be
structured, and what the templates should look like. This first pass will be
a great boon in having something concrete to talk about.

I'm really excited about this!

Best Regards-
-Doug



On 6/10/13 12:18 AM, Max Polk wrote:

The first full upload of the MSDN-contributed JavaScript pages can
be found for review and comments at:

First set:


http://dev.maxpolk.org/msdnjs/index.php?title=Special:AllPages&from=Constants&to=Objects%2Farguments


  Second set:


http://dev.maxpolk.org/msdnjs/index.php?title=Special%3AAllPages&from=Objects%2Farguments&to=&namespace=0


  This was an automated process and if there are glitches in
formatting you see, please let me know.  The next step is to make
fixes based on comments, then upload to the test wiki for a final
review, and afterwards to webplatform.