Re: DOM API Docs Proposal

"document" and "window" are properties that represent the "Document" and
"Window" objects, respectively. For correctness, I think we should use
object names and not property names (despite the fact that they are known
as their property counterparts instead).


☆*PhistucK*


On Tue, Apr 16, 2013 at 7:49 PM, Patrick D'Souza <pdsouza@about.com> wrote:

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