Re: JavaScript documentation structure

Attempting to find a clear distinction I fear will be futile. The DOM
specification currently is referenced by nearly every other spec, including
those (I would argue) not related to the DOM itself, like IndexedDB,
through the use of DOM-Strings/Events/Exceptions. By the logic that any API
using interfaces from the DOM-spec is a DOM API, anything, short of the
core language, would be a DOM API. I find a more useful distinction to be
whether an API operates on the DOM-tree or not, however, classifying then
in terms of DOM or non-DOM would arguably be misleading.

Thus, it seems convenient not to make the distinction at all.


On Fri, Apr 5, 2013 at 12:07 AM, Scott Rowe <scottrowe@google.com> wrote:

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