W3C home > Mailing lists > Public > public-webplatform@w3.org > April 2013

Re: DOM API Docs Proposal

From: Patrick D'Souza <pdsouza@about.com>
Date: Tue, 16 Apr 2013 12:49:53 -0400
Message-ID: <516D8131.3000402@about.com>
To: Scott Rowe <scottrowe@google.com>
CC: "public-webplatform@w3.org" <public-webplatform@w3.org>
Scott,

Is there any specific reason to use Document instead of document in the 
example below. I think lowercase document makes sense in this case 
instead of Document. dom/apis/document/getElementById 
<http://docs.webplatform.org/wiki/dom/apis/document/getElementById>proposed:dom/Document/getElementById 
<http://docs.webplatform.org/w/index.php?title=dom/Document/getElementById&action=edit&redlink=1> 
The same would apply to Window as well.

I like this new structure and we should make sure that the breadcrumbs 
on the page reflect this structure. But, before we go ahead with any 
proposed changes to the structure of the urls, we should ensure that the 
old url structures have a 301 in place until they are completely off 
Google's index. A 301 would provide a good user experience as well for 
someone still trying to access content via the old links.

- Patrick

On 04/16/2013 12:16 PM, Scott Rowe wrote:
> Thanks to Julee, Patrick, and Ryan's fascinating site map, we have a 
> complete bird's-eye view of our content, which proved indispensable in 
> auditing our DOM API pages and formulating a plan for organizing them, 
> which I propose at the following location:
>
> http://docs.webplatform.org/wiki/WPD:Projects/DOM_API_docs
>
> To summarize, proposed is the following URL pattern in reorganizing 
> the DOM API docs:
>
>   * dom/<object>/<member>     (where <member> is either a <property>
>     or <method>)
>   * dom/events/<event>
>
> This means that all objects would reside on the same level, i.e. 
> "dom/Window," "dom/Document," etc. to provide for the shortest URLs 
> possible. Events are getting their own namespace because usually the 
> event target is a general DOM Element, and distinguishing events by 
> their targets does not add any useful information to the URLs.
>
> You'll notice that the structure is very similar to that of the API 
> Docs[1], except for the omission of  <api name> interstitial, as in 
> "apis/webrtc" where "webrtc" is the name of an API_Listing page that 
> describes the common name of the API. These were necessary in the API 
> docs to avoid namespace collisions. They are not needed in the DOM API 
> docs.
>
> Note also the absence of the "apis" interstitial. The more I thought 
> about it, the less convinced I was that we needed it.
>
> Have a look at the proposal and let me know what you think.
>
> ~Scott
>
>
> [1] http://docs.webplatform.org/wiki/WPD:Projects/api_docs

-- 
Patrick D'Souza Developer, Metrics About.com | Do more 1500 Broadway, 
6th Floor New York, NY, 10036 AIM: padsouza
Received on Tuesday, 16 April 2013 16:50:28 UTC

This archive was generated by hypermail 2.4.0 : Friday, 17 January 2020 19:13:45 UTC