Re: JavaScript documentation structure

Yes, thanks for getting involved, Zacharias!

I agree with PhistuK that we should maintain a distinction between the
JavaScript language reference and the standard browser APIs. I also agree
that the distinction between DOM APIs and so-called HTML5 APIs (or, just
APIs, as we call them) is not clear and probably should be reconsidered.
Because PhistucK is right that for most of these, the "key" method is
usually a member of a DOM top-level node object. See IndexedDB's
Window.IndexedDB.open() or WebRTC's Navigator.getUserMedia(). However, the
key method is used only once, and thereafter no further consideration of
DOM objects is necessary to work with the API. Also, recall that traversing
the DOM proper is expensive compared to calling the HTML5 APIs. That's the
distinction between API and DOM API.

For the API Project[1], we separated these APIs from the DOM APIs mostly
for convenience. We needed to develop a methodology[2] for writing API
documentation, to answer some basic questions - and surface issues -about
the information architecture, and to walk the path of reorganizing the mess
and filling the holes in the imported content. The result of the API
project is a cogent presentation that will inform our tackling of the DOM
API documentation.

I invite everyone interested to get acquainted with the DOM architecture,
our current DOM content, and consider the ways we might structure our
documentation. On the one hand we have the luxury of documenting a model
that is already defined in terms of a model (the M in DOM), on the other,
we are constrained to essentially one perspective on that model by virtue
of our requirement that the information architecture be delineated in our
URLs. Moreover, we need to keep those URLs short.

Anyway, I'm developing a proposal for the DOM APIs with all of these
considerations. I encourage, nay BEG, that others become acquainted with
the problem and get prepared to discuss their ideas.

~Scott


[1] http://docs.webplatform.org/wiki/WPD:Projects/api_docs
[2] http://docs.webplatform.org/wiki/WPD:Creating_API_pages
[3] http://docs.webplatform.org/wiki/apis/audio-video









On Wed, Apr 3, 2013 at 1:47 AM, Chris Mills <cmills@w3.org> wrote:

> 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)
>