Fwd: Re: JS Information Architecture for WebPlatform.org

Hi, folks–

Here's some feedback we got from Rick Waldron from Bocoup (and TC-39) on 
the JavaScript project.

Regards–
–Doug


-------- Original Message --------
Subject:  Re: JS Information Architecture for WebPlatform.org
Date:  Fri, 9 Aug 2013 13:14:17 -0400
From:  Rick Waldron <waldron.rick@gmail.com>
To:  Doug Schepers <schepers@w3.org>






On Fri, Aug 9, 2013 at 11:57 AM, Doug Schepers <schepers@w3.org
<mailto:schepers@w3.org>> wrote:

     Hi, Rick–

     I hope you're doing well.

     You're one of a small number of people I'm contacting to help us
     with some guidance on how we should structure our JavaScript docs at
     WebPlatform.org [1]. I'd really appreciate your insight, if you have
     the time (which should only be a few minute for a first-pass glance,
     more if you're really into it).


     We are importing a bunch of reference articles documents on JS from
     MSDN, which is actually a pretty good starting point; obviously, we
     wil want to flesh them out more, but we want to get this initial
     import right.

     We want the docs to be structured in a way that's useful and
     intuitive for developers, but also technically correct from a
     language-design point of view. This is reflected in 3 things:

     1) URL hierarchy
     2) Page structure
     3) Categorization (tags)

     Would you mind taking a look at what we have so far for these, as a
     sanity check? The big one right now is URL hierarchy; if you have
     time to look at the other items, that would be gravy.


     ==URL hierarchy==

     We have a write-up of the current thinking for the URL structure
     [1][2]. On the table on github, "Page name" contains the relative
     URL for each article; for example "Objects/Array/length Property"
     would be an article named "length Property" at the URL:
     http://docs.webplatform.org/__wiki/javascript/Objects/Array/__length
     <http://docs.webplatform.org/wiki/javascript/Objects/Array/length>
     Property


This is good, but I would prefer to see one step further in the
organization; if the article is about Array.prototype.length, then the
url should be:

http://docs.webplatform.org/wiki/javascript/Objects/Array/prototype/length

The reason I think this is important is because there are at least 2 new
ES6 static methods on the Array object (and likely more to come), so
those would look like:

Array.from:
http://docs.webplatform.org/wiki/javascript/Objects/Array/from

Array.of:
http://docs.webplatform.org/wiki/javascript/Objects/Array/of

(this already exists, but would fall under the same url pattern)
Array.isArray
http://docs.webplatform.org/wiki/javascript/Objects/Array/isArray


If these shared a url path "space" with method of the prototype, it
would be unclear which was a static Array "class-side" method or a
method of Array instances, ie. Array.prototype


I would even consider removing the "Objects" part from the path, since
that's implicit. There are no non-object things in the [[Global]] object
(assuming we accept that functions are objects)

http://docs.webplatform.org/wiki/javascript/Object/[[static]] (eg.
Object.defineProperties or in ES6: Object.assign and Object.mixin)
http://docs.webplatform.org/wiki/javascript/Object/prototype/[[instance]] (eg. 

hasOwnProperty, isPrototypeOf)

http://docs.webplatform.org/wiki/javascript/Array/[[static]] (eg.
Array.isArray, Array.from, Array.of)
http://docs.webplatform.org/wiki/javascript/Array/prototype/[[instance]]
(eg. length, slice, forEach)

http://docs.webplatform.org/wiki/javascript/Function/[[static]] (eg.
Function.name)
http://docs.webplatform.org/wiki/javascript/Function/prototype/[[instance]]
(eg. call, apply, bind)

http://docs.webplatform.org/wiki/javascript/Date/[[static]] (eg.
Date.now, Date.parse)
http://docs.webplatform.org/wiki/javascript/Date/prototype/[[instance]]
(eg. getSeconds, getYear)


Or, you could replace "Objects" with "API" for those above (and
everything in Chap 15 of ES5.1/6), which would allow for a "syntax" path:

given:
http://docs.webplatform.org/wiki/javascript/API/Array/[[static]]

You might have:
http://docs.webplatform.org/wiki/javascript/syntax/function-declaration
http://docs.webplatform.org/wiki/javascript/syntax/function-expression
http://docs.webplatform.org/wiki/javascript/syntax/module-declaration
http://docs.webplatform.org/wiki/javascript/syntax/while-statement

and so forth


Rick




     (Note that MediaWiki is case-sensitive for URLs; we're moving to a
     system that's not.)


     ==Page structure==

     We're more or less structuring each page like they have on MSDN [4],
     but if you have the gumption to suggest how to optimize this for
     developer consumption, we're all ears.


     ==Categorization==

     In addition to the exlicit URL structure, which clusters like things
     together (date stuff, array stuff), there might be other useful
     collections or categorizations of some or all of these things
     (beyond the obvious "javascript" tag). We haven't thought too deeply
     about this aspect, but if there are obvious implicit tag clusters
     that you think would help navigation and exploration, we'd be
     interested to hear about them.


     [1] http://docs.webplatform.org/__wiki/javascript
     <http://docs.webplatform.org/wiki/javascript>
     [2] http://docs.webplatform.org/__wiki/WPD:Projects/javascript
     <http://docs.webplatform.org/wiki/WPD:Projects/javascript>
     [3]
 
https://github.com/maxpolk/__msdn-js-conversion/blob/__master/round-alice/upload-__mapping.wiki
 
<https://github.com/maxpolk/msdn-js-conversion/blob/master/round-alice/upload-mapping.wiki>
     [4]
 
http://msdn.microsoft.com/en-__us/library/ie/yek4tbz0(v=vs.__94).aspx 
<http://msdn.microsoft.com/en-us/library/ie/yek4tbz0(v=vs.94).aspx>

     Thanks!
     -Doug

Received on Sunday, 3 November 2013 22:14:29 UTC