Re: Creating API pages

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