Re: Creating API pages

So, what is the definitive decision here?
I think we need to have one as soon as possible and to get everything
organized according to it.

Should dom/x only include DOM Level # (Core/Events/Foo)?

HTML APIs are, I guess, APIs that are defined within the HTML specification
(the WHATWG one? hehe).
However, larger concepts (such as canvas, video, audio) would have their
own sub namespaces (apis/canvas).
And smaller concepts could probably be thrown into the "dom" namespace.
So, yeah, I guess an HTML API namespace is not useful here, it would just
add confusion and the difference is pretty vague anyway.

Regarding JavaScript, I have not found any article for Object, so I guess
that should be created. Right?
I only see javascript/objects/Date.
I see there is a JavaScript Object template. Is there a reason for this
distinction? Should we use the API Object template for everything?

I have a long list of questions here, I think... everything gets too
confusing as you go deeper and deeper.

☆*PhistucK*



On Fri, Nov 9, 2012 at 9:18 PM, Scott Rowe <scottrowe@google.com> wrote:

> Hi Julee,
>
> Thanks for reviewing this. Let's see if I can address your questions...
>
>  1. Has it ever been clarified if WPD is documenting how JavaScript API
>> work in browser instances or if we are documenting APIs regardless of host
>> environment or language? (No strong opinion here, just wondering.)
>>
>
> I don't think this has been clarified, and probably should be. My thought
> is that wherever possible, we should note any browser-specific
> implementations. Most of the time this is handled in the Compatibility
> Table Notes section - for example, when a feature requires a flag to be
> set. I think the best place for including this is in the general editing
> guide.
>
>
>>
>> 2. Were do core JavaScript or globals go?
>>
>
> The javascript <http://docs.webplatform.org/wiki/javascript> namespace
> holds all JavaScript-specific documentation.
>
>
>>
>> 3. What about the apis under http://docs.webplatform.org/wiki/dom apis?
>>
>
> The dom namespace needs to be reevaluated, too, me thinks. Though this was
> not within the scope of this exercise. I hope that the architecture and
> methodology we develop for the apis will inform our overhaul of the dom
> namespace.
>
>
>>
>> 4. Also, kind of following that, instead of /apilist/objects/, why not
>> associate with the dom? So:
>>
>> /apis/document/properties/cookie
>> /apis/window/storage/localStorage/methods/
>> /apis/window/indexedDB/methods/
>> /apis/window/File/methods/
>>
>
> We're keeping the dom namespace separate from the apis namespace, as I
> understand it. I think the non-dom apis are more clearly defined on their
> own, and that fitting them within the dom does not add any value. While it
> is true that most of the time the API is accessed within the context of a
> dom object, i.e. navigator.getUserMedia() and window.indexedDB.open(),
> usually this context is only necessary to create the initial object, i.e. a
> LocalMediaStream object or an IDBOpenDBRequest object. That much is
> adequately covered in the documentation and needn't be spelled out in the
> URLs.
>
>
>>
>> 5. Would it be useful to have dom, bom, cssom, svgom? Or is that a
>> hairball...
>>
>
> Again, I would treat those as separate namespaces and their organization
> as a separate exercise. That said, we do have some cssom stuff. See the Category:CSS
> page <http://docs.webplatform.org/wiki/Category:CSS>.
>
>
>>
>> 6. If we put all of the APIs under /apis/, we also have this page:
>> /html/apis. This will continue to be the list all of the HTML API that
>> reside under /apis/? Not sure how meaningful that list is. For example, it
>> has getUserMedia(), but not the MediaStream object. Maybe, instead, we
>> could have concept pages, such as media_capture_and_stream or
>> client_storage, where you could list all of the relevant API?
>>
>
> I don't think the html/apis page<http://docs.webplatform.org/wiki/html/apis> is
> useful, and it's probably a mistake. It has only one link that refers to
> the File API as apis/file <http://docs.webplatform.org/wiki/apis/file>.
> All of the other labels in the list (they are not linked) also refer to
> APIs that belong to the apis namespace, and none of these is an HTML API as
> I understand it. What is an HTML API anyway?
>
>
>>
>> 7. Topic_hierarchy still has apis under topic areas and architecture is
>> out of date. Can we review these and confirm current location or provide
>> location of move?
>>
>
> Yes, we need to update both the WPD:Architecture<http://docs.webplatform.org/wiki/WPD:Architecture>and
> WPD:Content/Topic_Hierarchy<http://docs.webplatform.org/wiki/WPD:Content/Topic_Hierarchy>pages. These could be better organized, too. In fact, I'd like to revisit
> the entire WPD: namespace, but that's a separate project.
>
>
>>
>> 8. Where do the images or other files associated with the page reside?
>>
>
> The usual treatment: any images or files may be attached to the page. The
> wiki stores all images in a database and refers to them by id.
>
>
>>
>> Thanks!
>>
>> Julee
>>
>>
> Thanks to you, Julee!
> +Scott
>
>
>>
>>
>>
>>
>> From:  Scott Rowe <scottrowe@google.com>
>> Date:  Thursday, November 8, 2012 11:25 PM
>> To:  Alex Komoroske <komoroske@google.com>
>> Cc:  "public-webplatform@w3.org" <public-webplatform@w3.org>
>> Subject:  Re: Creating API pages
>>
>>
>> Thank you frozenice and Alex for nailing that bug!
>> Earlier Alex had asked for a summary of the methodology and architecture
>> proposed. I appreciate the need for greater clarity.
>>
>> == Problem ==
>>
>> Contributors and users cannot create and locate pages in the apis
>> namespace because the namespace architecture is inadequate to the task.
>> The architecture has the following problems:
>>
>> * Does not differentiate between an API¹s common name (WebRTC) and the
>> actual JavaScript objects that provide the programmatic API (MediaStream).
>> More...
>> <
>> http://docs.webplatform.org/wiki/WPD:Creating_API_pages#No_differentiation
>> _between_objects_and_listings>
>>
>> * Inaccurately describes the relationship between the API objects and
>> their members - events, methods, and properties (by omitting the object
>> identifier or using the wrong casing on it). More...
>> <
>> http://docs.webplatform.org/wiki/WPD:Creating_API_pages#Delineation_is_ina
>> ccurate>
>>
>> * Does not provide for duplicate member names of the same member type, for
>> example two properties named label, each a property of a different object.
>> More...
>> <
>> http://docs.webplatform.org/wiki/WPD:Creating_API_pages#Dublicate_names_in
>> _conflict>
>>
>> Problems with forms and templates are somewhat related to the problems
>> with the architecture. Various fixes to these are needed to round out the
>> larger solution for usability. More...
>> <
>> http://docs.webplatform.org/wiki/WPD:Creating_API_pages#Template_and_form_
>> fixes_needed>
>>
>> == Solution ==
>>
>> A methodology for creating new content is part of the solution.
>>
>> * For each common-name API, create only one API Listing page as a top
>> level page for the API; follow casing rules; include any other common
>> names for the API in the page content; consistently follow the
>> methodology, even for singleton APIs. More...
>> <http://docs.webplatform.org/wiki/WPD:Creating_API_pages#Listing_page>
>>
>> * Introduce a new namespace identifier, objects and locate all api object
>> pages under it.  More...
>> <
>> http://docs.webplatform.org/wiki/WPD:Creating_API_pages#Stubbing_out_the_p
>> ages>
>>
>> Also, a new architecture is needed.
>>
>> * The proposed new architecture is as follows:
>>
>> apis
>> apis/apilist
>> apis/apilist/objects/apiObject/events
>> apis/apilist/objects/apiObject/methods
>> apis/apilist/objects/apiObject/properties
>>
>> More clarity about how to create the pages is required.
>>
>> * Provide guidelines to creating URLs for API pages in the WPD:New_Page
>> <http://docs.webplatform.org/wiki/WPD:New_Page> page.
>>
>> * Develop the forms and templates used in creating new apis pages. TODO¹s
>> in this section
>> <
>> http://docs.webplatform.org/wiki/WPD:Creating_API_pages#Filling_in_the_pag
>> es>
>>
>> Implied with this methodology is the need to reorganize the existing
>> content according to the new model.
>>
>> +Scott
>>
>>
>>
>> On Thu, Nov 8, 2012 at 1:58 PM, Alex Komoroske <komoroske@google.com>
>> wrote:
>>
>>
>>
>> On Thu, Nov 8, 2012 at 1:38 PM, Scott Rowe <scottrowe@google.com> wrote:
>>
>> Hi Alex,
>> When I visit the page, apis/indexedDB/properties/direction
>> <http://docs.webplatform.org/wiki/apis/indexedDB/properties/direction>,
>> no
>> text (like "Property of apis/indexedDB/IDBCursor") appears on the page.
>> Nor does such text appear on the other properties pages of IDBCursor, even
>> though all of these pages do have "apis/indexedDB/IDBCursor" in the
>> Applies_to field.
>>
>>
>>
>>
>>
>> That was an odd bug. I just fixed it (although I'm not entirely sure how;
>> the change I made should have netted to a no-op).
>>
>>
>> The methods pages of IDBCursor, such as apis/indexedDB/methods/advance
>> <http://docs.webplatform.org/wiki/apis/indexedDB/methods/advance> do have
>> the text.
>>
>> There is a bug somewhere. This is not a caching problem. I'll continue to
>> look into it. I appreciate your advice.
>>
>> +Scott
>>
>>
>>
>> On Thu, Nov 8, 2012 at 1:04 PM, Alex Komoroske <komoroske@google.com>
>> wrote:
>>
>> Hi Scott,
>> Thanks for writing this up!
>>
>> The organization is confusing me a bit since it bounces back and forth
>> between between critiquing the current setup, proposing changes, and
>> describing how to practically accomplish things in the current set-up (I
>> think? It may describe how to accomplish things in the hypothetical
>> future). Is there a crisp summary of the changes you propose?
>>
>> Also, note that your point about the Applies_to field not working for
>> things like apis/indexedDB/IDBCursor is incorrect--it was actually just a
>> caching problem. After you update the applies_to field, you often need to
>> do a hard refresh (Edit > Refresh from within the page) of the page where
>> you want it to show up.  We should document this somewhere, perhaps next
>> to the Applies_to field itself.
>>
>> --Alex
>>
>>
>>
>> On Thu, Nov 8, 2012 at 12:03 PM, Scott Rowe <scottrowe@google.com> wrote:
>>
>> When I sat down to document the process for creating API pages, using the
>> WebRTC documentation as the poster child, I found more questions than
>> answers. I realized that we did not have a good story here, so I did my
>> best to fill in the holes with a methodology that attempts to solve the
>> problems I found.
>> You find this methodology described in WPD:Creating_API_pages
>> <http://docs.webplatform.org/wiki/WPD:Creating_API_pages>.
>>
>> Note that it started out as a how-to for contributors, but quickly became
>> a proposal. So parts of it will read either way. Don't be alarmed. The
>> purpose of the document is to provide you with a methodology to try on as
>> you do what I did - test it out with your own API pages.
>>
>> As you do, please don't update the methodology in that page - let's
>> discuss it first. We can use this thread for the discussion.
>>
>> Thanks for your help!
>>
>> +Scott
>>
>>
>>
>>
>>
>>
>>
>>
>>
>>
>>
>>
>>
>>
>>
>>
>>
>>
>>
>>
>>
>>
>>
>>
>>
>>
>>
>>
>>
>>
>>
>