Re: JavaScript documentation structure

I do not think DOM and APIs should be under JavaScript.

JavaScript is basically the ECMAScript standard and stuff that are pretty
platform (client, server, native) agnostic, but are part of the language,
or an accepted extension of it.

DOM and APIs are completely separate specifications, that can be
implemented in any language.
Currently, the best way to show the syntax, usage and example is by using
JavaScript (and HTML and CSS), but it is definitely not part of JavaScript.

I do think that the API and DOM distinction is too vague and APIs are
usually pretty interconnected with the rest of the DOM (due to common
types, or due to the fact that most interfaces or objects are actually
accessible by Window or Document and if I remember correctly, both of them
are DOM interfaces, or HTML5 interfaces). But I guess I somehow understand
that the distinction we currently have may somewhat help.


☆*PhistucK*


On Wed, Apr 3, 2013 at 2:18 AM, 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.
>
> 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.
>
> 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.
>
> Best regards,
> Zacharias
>