Re: Creating API pages

Hi PhistucK,

For the questions related to creating API pages, I think we should give
everyone a chance to read through the proposal, catch up with e-mail, and
respond to this post. Let's give it a few more days beyond the weekend.

For issues not related to this thread, like those with the dom namespace, I
recommend starting another thread.

Thanks,
+Scott



On Fri, Nov 9, 2012 at 12:21 PM, PhistucK <phistuck@gmail.com> wrote:

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