Re: JavaScript APIs organization

This does sound like a bit of a mess, agreed. 

First of all, we need to make sure http://docs.webplatform.org/wiki/WPD:Content/Topic_Hierarchy works. Does this work for JS, and we just need to move the pages so they are consistently placed? Or could this use some updating? This is the definitive document that defines the IA for the site.

2. Second, it would be painful for one or two people to have to go through and move all these pagers to the right place. I will add a section on making sure the page is in the right place in my guide I'm writing on editing/updating/creating new content. I'm aiming to write one of these for tutorials/concepts/references.

3. I will then try to raise some taskforces together to help work on getting the existing documentation sorted out.



Chris Mills
Open standards evangelist and dev.opera.com editor, Opera Software
Co-chair, web education community group, W3C
Author of "Practical CSS3: Develop and Design" (http://my.opera.com/chrismills/blog/2012/07/12/practical-css3-my-book-is-finally-published)

* Try Opera: http://www.opera.com
* Learn about the latest open standards technologies and techniques: http://dev.opera.com
* Contribute to web education: http://www.w3.org/community/webed/

On 15 Oct 2012, at 10:07, Dominique Hazael-Massieux <dom@w3.org> wrote:

> Hi,
> 
> It looks like the current organization of the documentation for
> JavaScript APIs (and in particular their methods and properties) is a
> bit of a mess.
> 
> Some are documented in sub-pages of
> http://docs.webplatform.org/wiki/apis (grouped in somewhat arbitrary
> fashion), some are documented under http://docs.webplatform.org/wiki/dom
> (see http://docs.webplatform.org/wiki/dom/methods to get an idea).
> 
> The organization under http://docs.webplatform.org/wiki/dom is also very
> messy, since methods and properties are put directly under
> http://docs.webplatform.org/wiki/dom/methods and
> http://docs.webplatform.org/wiki/dom/properties, not under a specific
> interface, so name clashs are pretty much guaranteed down the line.
> 
> I'm not sure what the intent of the "apis/" space is; maybe is it for
> documenting APIs at a high level, while leaving specific documentation
> to sub pages in dom/... ? That probably ought to be clarified at the
> very least.
> 
> I also suggest the whole dom/ subtree be re-organized to move properties
> and methods to their specific interfaces, e.g. move
> dom/properties/attribute (sic) to dom/Element/attributes (I'm not sure
> we need to distinguish them in subtree properties / methods, but I would
> be fine either way). Otherwise, name clashes are guaranteed.
> 
> Also, is it the intent that properties and methods of objects such as
> window or navigator be also documented under the dom/ subtree? 
> 
> What about Math.*?
> 
> Thanks for any input!
> 
> Dom
> 
> 
>

Received on Monday, 15 October 2012 09:31:46 UTC