- From: Doug Schepers <schepers@w3.org>
- Date: Sun, 03 Nov 2013 17:14:40 -0500
- To: WebPlatform Community <public-webplatform@w3.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