W3C home > Mailing lists > Public > public-webplatform@w3.org > April 2013

JavaScript documentation structure

From: Zacharias Knudsen <zachasme@gmail.com>
Date: Wed, 3 Apr 2013 01:18:01 +0200
Message-ID: <CABZAvrAdA+Rekhn3P0fFGO9NSnN4ry2-wAO34_=JKcmLP4tZjg@mail.gmail.com>
To: public-webplatform@w3.org
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
Received on Wednesday, 3 April 2013 08:10:10 UTC

This archive was generated by hypermail 2.4.0 : Friday, 17 January 2020 19:13:45 UTC