Re: Creating API pages

Thanks Mike - I really appreciate the help here! My bits in-line...


On Thu, Nov 15, 2012 at 9:43 AM, Mike Sierra <
letmespellitoutforyou@gmail.com> wrote:

> Replies inlined "SIERRA":
>
> On Thu, Nov 15, 2012 at 12:12 PM, Scott Rowe <scottrowe@google.com> wrote:
> > Thanks Mike!
> > I'd like to add some clarification, if I may...
> >
> >
> > On Thu, Nov 15, 2012 at 7:59 AM, Mike Sierra
> > <letmespellitoutforyou@gmail.com> wrote:
> >>
> >> Re "Action Item", Along with Julee, I plan to assemble a list of URLs
> >> based on interface declarations in a generous sample of W3C specs,
> >> with comments noting any items I run across that don't fit into the
> >> structure discussed in the meeting.  It appears throughout the
> >> meeting, I was unclear about the purpose of <apilist>, which was
> >> reflected in my notes for the action item. Let me clarify
> >> terminology:
> >>
> >> /apis/apiName/apiInterface/(property|method|event)
> >
> >
> > Is this change in terminology necessary? We were working from this:
> >
> > apis/<apilist>/<apiObject>/<event|method|property>
>
> SIERRA: Provisional change in terminology b/c I misunderstood
> somewhere along the way what <apilist> meant.  Came into the thread
> midstream, so sorry if I missed the details.
>
>
'Sokay! This is a long thread. A tl;dr if ever there was one! The original
proposal is here:
WPD:Creating_API_pages<http://docs.webplatform.org/wiki/WPD:Creating_API_pages>.
I'm in the midst of updating this for all of the issues resolved thus far.
It will be a lot easier to read once I'm done.


>
> >> * Where appropriate, note the DOM node used to access each interface
> >>   object: document, navigator, window, video, audio, etc.
> >
> >
> > Worth a try! If we can come up with something slicker than just a link in
> > the description, I'm all for it.
> >
> >>
> >>
> >> On this last point, perhaps remaining elements within dom/apis could
> >> then link back? I understand this will be the place for the remaining
> set
> >> of core DOM APIs.
> >
> >
> > I'm not sure what you mean here.
>
> SIERRA: Maybe I misunderstood the thread, but what I have in mind is
> ubiquitous DOM APIs such as classlist & dataset. Would these be under
> dom/ or apis/ ?
>

Ah, I see. Those go under dom. We have elected to make a distinction
between DOM and APIs because giving APIs like WebRTC or IndexedDB their own
namespace makes them easier to locate. It also allows us to focus on
solidifying the architecture of these APIs so that we can continue building
out the documentation for them. Of course, we will continue to build out
the dom namespace as well, but considerations for that namespace should be
made independently of the considerations for the apis namespace. The dom
namespace is just a whole lot bigger and more complex, and if we made the
apis namespace considerations dependent on the dom namespace
considerations, we might never be able to document things like WebRTC and
Web Audio API.



>
> >>
> >> --Mike Sierra
> >
> >
> > Thanks Mike!
> > +Scott
> >
>
> SIERRA: Thx, out.
>

Again, thanks Mike!
+Scott



>
>
>
> >> On Wed, Nov 14, 2012 at 6:12 PM, Scott Rowe <scottrowe@google.com>
> wrote:
> >> > Thanks to everyone who particpated on the call today to discuss the
> >> > proposal
> >> > and the apis architecture. Ahead of meeting notes, I'd like to review
> >> > some
> >> > of the main points and revisit the issues that were not fully resolved
> >> > at
> >> > the end of the call. It's rather imperative that we be able to move
> >> > forward
> >> > with the documenting the APIs, and I think we've resolved enough of
> the
> >> > issues to be able to move forward without having to do too much
> revising
> >> > or
> >> > reorganizing of our docs down the road.
> >> >
> >> > Could everyone please take a moment to read this and respond? Thanks!
> >> >
> >> > apis architecture
> >> >
> >> > We decided to remove the "intermediate" pages (objects, events,
> methods,
> >> > and
> >> > properties) from the namespace to keep the URLs shorter and eliminate
> >> > the
> >> > need to fill these pages with queries or redirects. The new api
> >> > namespace
> >> > architecture is as follows:
> >> >
> >> > apis
> >> > apis/<apilist>
> >> > apis/<apilist>/<apiObject>/<foo-event>
> >> > apis/<apilist>/<apiObject>/<bar-method>
> >> > apis/<apilist>/<apiObject>/<baz-property>
> >> >
> >> > Note: further discussion about the <apilist> namespace identifier is
> >> > further
> >> > on, but assumed here to be maintained.
> >> >
> >> > I will begin rewriting the proposal for this and reorganizing the
> webrtc
> >> > docs.
> >> >
> >> > constants
> >> >
> >> > We discussed the possibility of providing for constants (enumerations)
> >> > that
> >> > are shared across several methods within an object. I spoke with our
> own
> >> > Dimitri Glazkov about this. Turns out that an API may provide for the
> >> > case
> >> > where a property could use only part of the enumeration (values 1 and
> 2,
> >> > but
> >> > not 3) while another property would use all values (1, 2, and 3) of a
> >> > given
> >> > enumeration. Constants are defined for the object, so this scenario is
> >> > quite
> >> > common.
> >> >
> >> > Now the challenge is how to represent the valid constants for a
> >> > particular
> >> > property. We need a way to specify constants 1 and 2 (but not 3) for
> >> > property A, and specify constants 1, 2, and 3 for property B. Probably
> >> > the
> >> > best way is to follow the same approach we take with events, methods,
> >> > and
> >> > properties pages and the "Applies to" field.
> >> >
> >> > So, each constant would have its own page, i.e.
> >> > apis/<apilist>/<apiObject>/<FOO-constant> and the properties page
> would
> >> > have
> >> > a summary table listing each of the valid constants. The trick here
> >> > would be
> >> > to provide each <FOO-constant> page with multiple "Applies to" fields
> so
> >> > that these could be shared.
> >> >
> >> > This needs some thought and design expertise. For now, let's just move
> >> > forward with constants listed per property.
> >> >
> >> > exceptions
> >> >
> >> > We need to describe the exceptions for a method. Same re-use scenario
> as
> >> > with constants. So apis/<apilist>/<apiObject>/<Bar-exception> and the
> >> > ability to "Applies to" to different methods. Note that often API
> >> > methods
> >> > use DOM exceptions, so this template needs to work for both dom and
> >> > apis.
> >> > Could get kind of hairy with multiple "Applies to" fields.
> >> >
> >> > Needs some thought and design expertise, too. For now, let's just move
> >> > forward with exceptions listed per method.
> >> >
> >> > Move all apis under dom
> >> >
> >> > It was suggested that all of the api pages could be moved under the
> dom
> >> > namespace.
> >> >
> >> > Early on we decided to keep the dom namespace separate from the apis
> >> > namespace. The "non-dom" apis are more clearly defined on their own,
> and
> >> > fitting them within the dom does not add any value. While it is true
> >> > that
> >> > most of the time an API is accessed within the context of a dom
> object,
> >> > i.e.
> >> > navigator.getUserMedia() or  window.indexedDB.open(), usually this
> >> > context
> >> > is only necessary to create the initial object, i.e. a
> LocalMediaStream
> >> > object or an IDBOpenDBRequest object. That much is adequately covered
> in
> >> > the
> >> > documentation and needn't be spelled out in the URLs. And, as was
> >> > pointed
> >> > out in the call, our purpose is not to mimic the document object model
> >> > in
> >> > our URLs, but to provide for location and navigation. Furthermore,
> >> > nesting
> >> > everything under a DOM object page makes the URL longer.
> >> >
> >> > API Listing pages
> >> >
> >> > It was suggested that we remove the API Listing pages from the apis
> >> > namespace. I strongly urge us not to do so.
> >> >
> >> > The API listing pages describe the API by its common names - the names
> >> > by
> >> > which users search for information about the API. It provides for
> >> > find-ability where an API has multiple "listing names" - as is the
> case
> >> > with
> >> > the WebRTC API which is further sub-divided into the MediaStream,
> >> > PeerConnection, and DataChannel APIs. These need to be included as
> >> > sub-headings in the listing page to fully describe the API.
> >> >
> >> > The API listing pages provide an overview of how to use the API
> objects
> >> > included in the specification. The best place to do this is within the
> >> > apis
> >> > namespace, rather than a "concepts" or "guides" or other namespace.
> >> >
> >> > The API listing pages provide for disambiguation between like-named
> API
> >> > objects. Consider two objects:
> >> >
> >> > The MediaStreamAudioSourceNode object from the Web Audio API
> >> > The MediaStream object from the WebRTC API
> >> >
> >> > In fact, both of these are the same thing, as creating a
> >> > MediaStreamAudioSourceNode is simply passing to that object an object
> of
> >> > type MediaStream:
> >> >
> >> > MediaStreamAudioSourceNode createMediaStreamSource ( MediaStream
> >> > mediaStream
> >> > );
> >> >
> >> > If our URLs read, apis/MediaStreamAudioSourceNode and
> /apis/MediaStream
> >> > without any context to differentiate them, users are likely to get
> >> > confused.
> >> >
> >> > Action Item: Proving out the apis architecture
> >> >
> >> > I'm concerned that there may have been a miscommunication about the
> >> > action
> >> > item captured at the end of the meeting. This happened while the
> meeting
> >> > was
> >> > adjourning, and may have been misconstrued. Here's the snippet from
> the
> >> > IRC
> >> > channel:
> >> >
> >> > 9:57 AM <sierra_> TASK: someone sanity-check how actual APIs would
> work
> >> > 9:59 AM <sierra_> in apis/<apilist>/objects/<apiObject>/properties ,
> go
> >> > to
> >> > apis/APIobject/properties
> >> > 10:00 AM <sierra_> sorry, apis/APIobject
> >> >
> >> > What I heard was that the action item is to review the apis namespace
> to
> >> > see
> >> > if there would be collisions between api objects without the
> intervening
> >> > <apilist> object. First, it is unlikely that within our very limited
> >> > apis
> >> > namespace that this will happen (we currently have some 8 or 9 APIs,
> not
> >> > counting DOM APIs); second, we can never fully prove the lack of
> >> > collisions
> >> > because we don't have time to review the entire set of standard APIs -
> >> > and
> >> > we certainly can't vet the ones that haven't been created yet.
> >> >
> >> > Perhaps someone could fill in here why this exercise is necessary and
> >> > what
> >> > it hopes to prove?
> >> >
> >> > Would it not be more efficacious to simply proceed with maintaining
> the
> >> > <apilist> namespace identifier - as in
> >> > apis/<apilist>/<apiObject>/<etc.>?
> >> >
> >> > Thanks for helping out here!
> >> >
> >> > +Scott
> >> >
> >> >
> >> >
> >> >
> >> > On Tue, Nov 13, 2012 at 12:23 PM, PhistucK <phistuck@gmail.com>
> wrote:
> >> >>
> >> >> I am planning on adding fields for constants within the API Object
> >> >> template/form. It might take a few days, though. I hope to work on it
> >> >> on
> >> >> Friday or Saturday.
> >> >>
> >> >> ☆PhistucK
> >> >>
> >> >>
> >> >>
> >> >> On Tue, Nov 13, 2012 at 9:06 PM, David Gash <dgash@google.com>
> wrote:
> >> >>>
> >> >>> Scott,
> >> >>> For tomorrow's call, apart from the basic issue of the API content
> >> >>> architecture, let's discuss the web audio list before I set off
> >> >>> creating
> >> >>> ~150 pages. Also, I have a few questions about certain parts of the
> >> >>> interface that you (or someone else) may be able to answer, below.
> The
> >> >>> numbers refer to the W3C spec, and are linked to the specific
> sections
> >> >>> for
> >> >>> easy reference.
> >> >>>
> >> >>> 4.3 AudioSourceNode
> >> >>> Listed as an "abstract" interface, has no documented properties or
> >> >>> methods.
> >> >>>
> >> >>> 4.11 MediaElementAudioSourceNode
> >> >>> Created in an Audiocontext, has no documented properties or methods.
> >> >>>
> >> >>> 4.14.1 PannerNode Constants
> >> >>> There's no API structure/path for constants.
> >> >>>
> >> >>> 4.18 ChannelSplitterNode and
> >> >>> 4.19 ChannelMergerNode
> >> >>> Also have no documented properties or methods.
> >> >>>
> >> >>> 4.24 WaveTable and
> >> >>> 4.25 MediaStreamAudioSourceNode
> >> >>> Also have no documented properties or methods.
> >> >>>
> >> >>> I'm not sure whether to create pages for the objects with no
> >> >>> properties
> >> >>> or methods, and whether to document the PannerNode constants as
> >> >>> properties
> >> >>> or... something else. Any input appreciated.
> >> >>>
> >> >>> Dave
> >> >>>
> >> >>>
> >> >>>
> >> >>> On Mon, Nov 12, 2012 at 12:06 PM, Scott Rowe <scottrowe@google.com>
> >> >>> wrote:
> >> >>>>
> >> >>>> Thanks Dave! Be sure to share any issues you encounter on this
> >> >>>> thread.
> >> >>>> +Scott
> >> >>>>
> >> >>>>
> >> >>>>
> >> >>>> On Mon, Nov 12, 2012 at 11:16 AM, David Gash <dgash@google.com>
> >> >>>> wrote:
> >> >>>>>
> >> >>>>> Scott / all,
> >> >>>>>
> >> >>>>> I'm starting to document the web audio API. Based on Scott's
> >> >>>>> proposal
> >> >>>>> doc and the W3C specs, the first few topics' URLs will be
> structured
> >> >>>>> thus:
> >> >>>>>
> >> >>>>> apis/webaudio
> >> >>>>>
> >> >>>>> apis/webaudio/objects/AudioContext/properties/destination
> >> >>>>> apis/webaudio/objects/AudioContext/properties/sampleRate
> >> >>>>> apis/webaudio/objects/AudioContext/properties/currentTime
> >> >>>>> apis/webaudio/objects/AudioContext/properties/listener
> >> >>>>> apis/webaudio/objects/AudioContext/properties/activeSourceCount
> >> >>>>> apis/webaudio/objects/AudioContext/methods/createBuffer
> >> >>>>> apis/webaudio/objects/AudioContext/methods/decodeAudioData
> >> >>>>> apis/webaudio/objects/AudioContext/methods/createBufferSource
> >> >>>>> apis/webaudio/objects/AudioContext/methods/. . . etc.
> >> >>>>>
> >> >>>>> apis/webaudio/objects/AudioNode/properties/context
> >> >>>>> apis/webaudio/objects/AudioNode/properties/numberOfInputs
> >> >>>>> apis/webaudio/objects/AudioNode/properties/numberOfOutputs
> >> >>>>> apis/webaudio/objects/AudioNode/methods/connect
> >> >>>>> apis/webaudio/objects/AudioNode/methods/disconnect
> >> >>>>>
> >> >>>>> apis/webaudio/objects/. . . etc.
> >> >>>>>
> >> >>>>> There are a lot more objects, properties, and methods in this API,
> >> >>>>> of
> >> >>>>> course, but Scott has reviewed this plan and, barring any
> >> >>>>> objections, that's
> >> >>>>> the path structure I'll be following.
> >> >>>>>
> >> >>>>> I plan to outline the entire set before creating any pages, then
> >> >>>>> create
> >> >>>>> all the stubs, then go back and fill in.
> >> >>>>>
> >> >>>>> Cheers,
> >> >>>>> Dave
> >> >>>>>
> >> >>>>>
> >> >>>>>
> >> >>>>> On Thu, Nov 8, 2012 at 12:03 PM, Scott Rowe <scottrowe@google.com
> >
> >> >>>>> wrote:
> >> >>>>>>
> >> >>>>>> When I sat down to document the process for creating API pages,
> >> >>>>>> using
> >> >>>>>> the WebRTC documentation as the poster child, I found more
> >> >>>>>> questions than
> >> >>>>>> answers. I realized that we did not have a good story here, so I
> >> >>>>>> did my best
> >> >>>>>> to fill in the holes with a methodology that attempts to solve
> the
> >> >>>>>> problems
> >> >>>>>> I found.
> >> >>>>>>
> >> >>>>>> You find this methodology described in WPD:Creating_API_pages.
> >> >>>>>>
> >> >>>>>> Note that it started out as a how-to for contributors, but
> quickly
> >> >>>>>> became a proposal. So parts of it will read either way. Don't be
> >> >>>>>> alarmed.
> >> >>>>>> The purpose of the document is to provide you with a methodology
> to
> >> >>>>>> try on
> >> >>>>>> as you do what I did - test it out with your own API pages.
> >> >>>>>>
> >> >>>>>> As you do, please don't update the methodology in that page -
> let's
> >> >>>>>> discuss it first. We can use this thread for the discussion.
> >> >>>>>>
> >> >>>>>> Thanks for your help!
> >> >>>>>>
> >> >>>>>> +Scott
> >> >>>>>>
> >> >>>>>
> >> >>>>
> >> >>>
> >> >>
> >> >
> >
> >
>