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_inaccurate>
 *
*
* 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_pages>
*
*
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_pages>
*
*
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
>>>>
>>>>
>>>
>>
>