A categorization/placing problem - event/property pages

Hi all,

I am mailing to discuss a consistency problem we have come up against in the properties/events pages on webplatform.org; I have been discussing this with Frederic Hemberger, who took part in the Berlin doc sprint. The question is, how to categorise properyy and event pages.

Crawling through the properties list (http://docs.webplatform.org/w/index.php?title=Category:API_Object_Properties) we have 40 event related properties:

apis/file/properties/onabort
apis/indexeddb/IDBTransaction/onabort
apis/webrtc/RTCPeerConnection/onaddstream
apis/webrtc/MediaStreamTrackList/onaddtrack
apis/webaudio/ScriptProcessorNode/onaudioprocess
apis/indexeddb/IDBOpenDBRequest/onblocked
apis/indexeddb/IDBVersionChangeRequest/onblocked
apis/appcache/ApplicationCache/oncached
apis/appcache/ApplicationCache/onchecking
apis/indexeddb/IDBTransaction/oncomplete
apis/webrtc/RTCPeerConnection/ondatachannel
apis/appcache/ApplicationCache/ondownloading
apis/webrtc/MediaStream/onended
etc.

(Also, the File API is the only API listing those as "apis/file/properties/<propertyName>" instead of "apis/file/<propertyName>".)

On the other hand, the event page lists 54 API (61 if you include SVG) and 107 DOM event pages, rather than their related properties.

The questions is, how should we make these more consistent?

1. We could list these as event pages primarily, but then have another page for the event property in each case. So for example

http://docs.webplatform.org/wiki/apis/file/events/onabort could be the main page, with all the info on the event and its related property (but we'd be best changing onabort to abort)

http://docs.webplatform.org/wiki/apis/file/properties/onabort could just have a minimum of information on it, but point to the above page

2. We could do basically the same, but have the property pages as the main pages, and point the event pages to those.

3. We could just have the event pages, and make them cover both the properties and events:

http://docs.webplatform.org/wiki/apis/file/events/abort

And maybe have a silent redirect on the similar property page.

We (myself and Frederic) would rather go with moving the 40odd existing property pages to the Events listing and not treat them as "real" properties for the sake of documentation consistency (although this might be less precise from an implementation point of view). 

Otherwise, we'd need to move all API events to properties (if you think of DOM events as a "special breed"), and/or make duplicate (or at least very similar) pages. We are more interested here in what is most implementable/findable, rather than what is most technically correct.

Thoughts?

Chris Mills
Opera Software, dev.opera.com
W3C Fellow, web education and webplatform.org
Author of "Practical CSS3: Develop and Design" (http://goo.gl/AKf9M)

Received on Wednesday, 13 February 2013 17:04:19 UTC