Re: Creating API pages

Hi, Scott:

Thanks much for the write-up and this summary. Getting the right URL
pattern could result in greater discoverability. This gave me a clearer
sense of where things are going and food for thought.

A few 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.)

2. Were do core JavaScript or globals go?

3. What about the apis under http://docs.webplatform.org/wiki/dom apis?

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/

5. Would it be useful to have dom, bom, cssom, svgom? Or is that a
hairball...

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?

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?

8. Where do the images or other files associated with the page reside?

Thanks!

Julee





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

Received on Friday, 9 November 2012 16:57:54 UTC