Re: URL structure sanity check

I'm inclined to agree with Paul here. Using his example of 
PerformanceTiming there are about *twenty* subpages.  That seems pretty 
excessive to me.  I think his idea of using one comprehensive page is 
good, but making sure headings are setup properly so if people want to 
point to a specific thing or know where they are going they can easily 
use a fragment to do it.  I'm also seeing some with only two or three 
subpages; having those seems almost wasted for so little content when 
one page could do just fine with the information.

I am not sure what was said during the telcon for this though.  If there 
was a technical reason for wanting to use sub-pages then please let me 
know.  I think we could get the forms/templates setup pretty well for 
having one page handle all that is needed though.

-Garbee

On 11/15/2012 6:33 PM, Paul Irish wrote:
> I've long proposed shorter URLs and still think they are a better 
> match for our audience than over-specifying and using spec vocabulary.
>
> However,
>
> Given this list, I feel like the larger issue is one of granularity. 
> There simply isn't a good reason all  the PerformanceTiming events 
> (for example) should get their own page. performance.timing deserves 
> ONE page that's comprehensive.
>
> Our imported content defined these conventions, though, as far as I 
> know, no one considered them. In nearly every page in the linked file 
> <https://github.com/mike-sierra/webplatform/blob/master/urls.txt>, I 
> would probably collapse it into its parent.
>
> I don't think we'll find an URL structure that is consistent, 
> technically accurate, using precise terminology, using developer 
> terminology, and simultaneously user-friendly. And that's okay. The 
> important thing is having high-value documentation. Pages that 
> developers read and are hugely impressed so much valuable content is 
> there.
>
>
> On Thu, Nov 15, 2012 at 10:51 PM, Michael Sierra <msierra@adobe.com 
> <mailto:msierra@adobe.com>> wrote:
>
>     Turns out there are quite a few collisions in these examples once
>     you strip out the 'on' prefixes from the event names:
>
>     /apis/file/FileReader/abort
>     /apis/file/FileReader/error
>     /apis/push/PushService/error
>     /apis/webcrypto/CryptoOperation/abort
>     /apis/webcrypto/CryptoOperation/complete
>     /apis/webcrypto/CryptoOperation/init
>     /apis/webrtc/DataChannel/close
>     /apis/websocket/WebSocket/close
>
>     --Mike Sierra
>
>
>
>     ________________________________________
>     From: PhistucK [phistuck@gmail.com <mailto:phistuck@gmail.com>]
>     Sent: Thursday, November 15, 2012 5:33 PM
>     To: Michael Sierra
>     Cc: public-webplatform@w3.org <mailto:public-webplatform@w3.org>
>     Subject: Re: URL structure sanity check
>
>     In some cases (WebSocket, for example, if I am not mistaken), you
>     cannot use addEventListener for listening to an event, like
>     ws.onopen. Adding it as "open" might cause some confusion.
>     It might be an implementation issue, because I think WebSocket is
>     specified to subclass EventTarget as well, which means
>     addEventListener should apply to it, but in Chrome, as far as I
>     remember, it does not work. I have not tried other browsers.
>     Anyway, in cases like these (assuming no browser implements
>     addEventListener for that object), events should begin with the
>     "on" prefix, I believe (but still have the regular Event template,
>     I guess).
>
>     What does everyone think?
>
>     Also, does anyone have any information regarding other browsers
>     (or current Chrome?) in this regard?
>
>
>     ☆PhistucK
>
>
>
>     On Thu, Nov 15, 2012 at 11:18 PM, Michael Sierra
>     <msierra@adobe.com
>     <mailto:msierra@adobe.com><mailto:msierra@adobe.com
>     <mailto:msierra@adobe.com>>> wrote:
>     Re the recent conf-call clarifying the apis/ URL space, here are a
>     few random APIs generated from some test W3C specs:
>
>     https://github.com/mike-sierra/webplatform/blob/master/urls.txt
>
>     Of all the comments are marked "#",
>
>     * I think of "deviceorientation" as belonging under apis/, but it
>     seems to simply modify the window object.  Can/should it be
>     represented here?
>
>     * The File API defines a new URL scheme, and I wonder where that
>     gets doc'ed
>
>     * I noticed one instance of a namespace collision, where an
>     abort() method collides with an "abort" event.  In this URL list,
>     I kept it as it appears in the spec, "onabort," but current
>     practice in the wiki is to strip the "on" prefix, which would
>     cause a problem.
>
>     --Mike Sierra
>
>
>
>