meeting minutes re API doc structure conf-call

Julee suggested I post raw minutes from yesterday's meeting here, & just
got around to it:

[11:59am] sierra_: meet here? will scribe if so
[12:00pm] julee_: yes, thanks much!
[12:00pm] sierra_: ALEX is on call
[12:00pm] sierra_: JuLee is on call
[12:01pm] sierra_: Randy Nielsen from Adobe on call
[12:01pm] sierra_: Mike SIerra is here
[12:01pm] sierra_: ALEX == jkomoros
[12:01pm] sierra_: Elliott from MS
[12:02pm] sierra_: Doug is on call
[12:02pm] jkomoros: Doug == shepazu
[12:02pm] sierra_: Dave Gash @ google is on call
[12:03pm] sierra_: Scott & Peter @ google on call
[12:04pm] jrunrandy joined the chat room.
[12:04pm] eliot_ joined the chat room.
[12:05pm] jkomoros: Garbee, are you there?
[12:05pm] julee_: http://docs.webplatform.org/wiki/WPD:Creating_API_pages
[12:05pm] sierra_: Scott wrote article, re…
[12:06pm] sierra_: doc is procedural, and a proposal
[12:06pm] julee_: Summary was sent via email:
[12:06pm] sierra_: doc outlines creation of API pages
[12:07pm] julee_: From: Scott Rowe <scottrowe@google.com>
[12:07pm] julee_: Date: Thursday, November 8, 2012 11:25 PM
[12:07pm] julee_: Subject: Re: Creating API pages
[12:07pm] jswisher joined the chat room.
[12:07pm] sierra_: doc asserts proposed standards
[12:08pm] sierra_: these proposals require infrastructure improvements
[12:08pm] sierra_: propsed architecture: API, API lists, API objects
[12:08pm] julee_: @sierra_: that is shepazu speaking
[12:08pm] jkomoros: that's shepazu talking
[12:09pm] sierra_: shepazu unclear which are string literals & which
placeholders
[12:09pm] peterlubbers joined the chat room.
[12:10pm] sierra_: where do events, methods, properties go?
[12:10pm] sierra_: refreshing page as we go?
[12:11pm] sierra_: apis
[12:11pm] sierra_: apis/<apilist>
[12:11pm] sierra_: apis/<apilist>/objects/<apiObject>/events/<foo>
[12:11pm] sierra_: apis/<apilist>/objects/<apiObject>/methods/<bar>
[12:11pm] sierra_: apis/<apilist>/objects/<apiObject>/properties/<far>
[12:11pm] sierra_: example of apiarist is webRTC
[12:11pm] sierra_: example of apiObject is MediaStream
[12:12pm] shepazu:
http://docs.webplatform.org/wiki/WPD:Creating_API_pages#Creating_the_API_Object_Method.2C_Property.2C_and_Event_pages
[12:13pm] sierra_: APIs limited to Methods, Properties, Events.
[12:13pm] sierra_: Perhaps Exceptions?
[12:13pm] sierra_: perhaps constants?
[12:14pm] scottrowe:
http://docs.webplatform.org/wiki/apis/webrtc/objects/MediaStreamTrack/properties/readyState
[12:15pm] sierra_: ready state values represented as raw bullet list
[12:16pm] sierra_: inclusion of objects namespace clarifies taxonomy?
[12:16pm] David_Bradbury joined the chat room.
[12:16pm] sierra_: step argues for brevity
[12:17pm] jkomoros: q+
[12:17pm] sierra_: perhaps another branch under apiarist?
[12:17pm] sierra_: corr: apilist
[12:18pm] sierra_: who's talking?
[12:18pm] sierra_: ALEX
[12:18pm] eliot_: ALEX = jkomoros
[12:18pm] sierra_: ALEX argues for removing objects node
[12:19pm] sierra_: need straightforward list
[12:20pm] sierra_: goug?
[12:20pm] sierra_: doug?
[12:20pm] sierra_: doug?
[12:20pm] jkomoros: sierra_: yeah that's Doug
[12:21pm] sierra_: any use case for seeing just an object's methods?
[12:21pm] sierra_: alex?
[12:22pm] sierra_: parallels elements, attributes, etc.
[12:23pm] sierra_: if (drop objects?) URL is short
[12:23pm] sierra_: if (use intermediate pages) need redirect to main API
page
[12:24pm] sierra_: eliminating objects may cause usability problem
[12:24pm] sierra_: users land on empty page => argument for removing objects
[12:25pm] sierra_: no compelling arguments to retain objects?
[12:25pm] sierra_: DECISION: objects out
[12:25pm] sierra_: pages can be easily moved
[12:25pm] sierra_: does move cause any conflicts? probably no
[12:26pm] sierra_: conflicts between same-name properties of different APIs?
[12:27pm] sierra_: PROBLEM: for ref pages, all methods/properties are
clustered together in URL
[12:28pm] sierra_: SCOTT: problem solved when duplicate property name
(e.g., "label")
[12:28pm] sierra_: title page "label (API name)"
[12:29pm] sierra_: ls
[12:29pm] sierra_: Q: will change break links?
[12:30pm] sierra_: migration is big implementation issue
[12:30pm] sierra_: for later
[12:30pm] sierra_: ISSUE: events, methods, properties
[12:31pm] sierra_: any case when methods & properties have same name?
[12:31pm] sierra_: NO possibility of methods & properties sharing namespace
[12:32pm] sierra_: use case: list methods/props separately?
[12:32pm] sierra_: use case: ID method/property by scanning URL
[12:33pm] sierra_: is current setup, separating events/methods/props into
separate tables, sufficient?
[12:34pm] sierra_: any collissions?
[12:34pm] sierra_: potential for event names to collide,
[12:34pm] sierra_: since they're not called directly?
[12:35pm] sierra_: site point chunks CSS props by arbitrary topic
[12:37pm] sierra_: in web audio API, any collisions ?
[12:37pm] sierra_: dave says NO
[12:38pm] sierra_: web audio has ~150 objects
[12:38pm] mstalfoort left the chat room. (Quit: kthxbai)
[12:38pm] sierra_: dave argues in favor of keeping nodes
[12:41pm] sierra_: scott says remote intermediate pages
[12:41pm] sierra_: along w/many others
[12:41pm] julee_: @sierra_: jswisher is speaking
[12:42pm] Garbee: jkomoros, I am around now.  Running my dads store though,
little time to actually talk.
[12:42pm] sierra_: potential collisions in JS appear to be theoretical
[12:43pm] sierra_: DECISION: remove them; deal with potential conflicts
later
[12:43pm] sierra_: doug?
[12:43pm] • shepazu nope
[12:43pm] jkomoros: If you refresh the page, i've updated the example block
[12:45pm] sierra_: in readystate page, raw constant values s/b represented
as template
[12:45pm] sierra_: enumerations are re-used
[12:46pm] sierra_: potentially ugly subset of ennumerations
[12:46pm] sierra_: unimaginable
[12:47pm] sierra_: that would be bad practice
[12:47pm] sierra_: newer specs are more standardized
[12:48pm] sierra_: ISSUE: how to transition to URL structure?
[12:48pm] sierra_: Julee question: within apiarist node, is WebRTC too
abstract?
[12:49pm] sierra_: Randy & sierra got cut off; will dial back
[12:51pm] sierra_: ...
[12:51pm] sierra_: …
[12:51pm] sierra_: BACK IN; summarize?
[12:52pm] sierra_: api listing pages allow explanation of how they work
together
[12:52pm] sierra_: APIs need place for expository material
[12:53pm] eliot_: Afraid I need to drop off. thank you, everyone
[12:53pm] sierra_: e.g., usually 1 DOM call to access API object
[12:53pm] sierra_: most APIs not thought of as "DOM" APIs
[12:53pm] sierra_: then where do they go?
[12:54pm] sierra_: how to refer to APIs from document, window, media, etc
[12:55pm] shepazu: here's a good starting point for mapping everything out
http://platform.html5.org/
[12:55pm] sierra_: getUserMedia is DOM call
[12:56pm] sierra_: shouldn't be nested under DOM object used to access API
[12:56pm] sierra_: ?
[12:57pm] sierra_: TASK: someone sanity-check how actual APIs would work
[12:59pm] sierra_: in apis/<apilist>/objects/<apiObject>/properties , go to
apis/APIobject/properties
[1:00pm] sierra_: sorry, apis/APIobject
[1:01pm] PhistucK joined the chat room.
[1:03pm] peterlubbers left the chat room. (Quit: peterlubbers)
[1:03pm] sierra_: platform.html5.org lists APIs
[1:05pm] jkomoros left the chat room. (Quit: jkomoros)
[1:06pm] jkomoros joined the chat room.
[1:06pm] sierra_: Julee will try to plug in APIs; sierra will help