Re: JavaScript documentation structure

On 3 Apr 2013, at 00:18, Zacharias Knudsen <zachasme@gmail.com> wrote:

> Hi everyone.
> 
> I am seeking to contribute to the JavaScript section of WPD, but, failing to figure out how that content is to be organized, recently joined this mailing list.

Hi Zacharias, and welcome! JS (esp core) is an area we are particularly understaffed on, so any input you can give will be very welcome.

> 
> Currently the content seems to be scattered throughout multiple sections, with a somewhat unclear structure and some duplicates (ie. documentation of the audio-video API in the DOM-section as well as the API-section). I realize that much of this content have been imported from other sources, and as such need only to be properly organized.

Scott Rowe from Google is the lead on the API/JS docs, so can tell you more conclusively, but from what I have seen, most work so far in this area has been done on the APIs, with precious little being done in other JS areas. We wanted to get APIs done first before going onto other areas, basically because it is a popular area, and a good standalone chunk of content to tackle.

The stuff in the APIs section should be the correct content to use, with the stuff in the DOM section being eventually merged with it/phased out.

> 
> By writing here, I hope to hear what, if any, have been decided upon in this regard. To start off the discussion, I will write down my thoughts on the optimal structure for the JavaScript part of the docs.
> 
> The way I see it, JavaScript, as a dialect of ECMAScript, is comprised of two things:
> 	• The core language, including syntax, types, etc,
> 	• and extensions to the global object, like the DOM bindings, XHR, and all the other APIs.
> That is, I would argue that everything not in the core is an API, including the DOM bindings (okay, the DOM spec itself is not part of JavaScript, but i gather WPD is meant to document technologies relevant to web-developers, which mean we are only interested in the DOM bindings in JavaScript). 
> 
> As such, a logical content structure would be something like this:
> 	• Javascript
> 		• Core
> 		• APIs
> 			• DOM
> 			• XHR
> 			• WebSockets
> 			• etc.
> Thus, for the landing page "areas", we could have simply the JavaScript core as one such "area", JavaScript APIs as another "area", and finally a few "shortcut areas" for the APIs we decide to be important enough (which would obviously include the DOM, and perhaps XHR/WebSocket).
> 
> Anyway, those are my thoughts. Looking forward to your input.

I think you are right in your definitions of JS, and what counts as an API. But our feelings were that DOM is kinds special - DOM scripting is a recognised entity that people will be likely to search for, so we decided to include it as a top level topic on its own (along with JS, and APIs). I guess we should decide if the top level DOM section is to be its own standalone set of pages, or just a shortcut to a DOM section that is actually contained with the APIs section, or even the JS section, depending on where it fits best. It really is about balancing absolute correctness and search-ability, thinking about how the average developer on the street is likely to categorise JS and related topics.

All the best,

Chris Mills
Opera Software, dev.opera.com
W3C Fellow, web education and webplatform.org
Author of "Practical CSS3: Develop and Design" (http://goo.gl/AKf9M)

Received on Wednesday, 3 April 2013 08:47:10 UTC