Re: Creating API pages

Yep.
The New_Page <http://docs.webplatform.org/wiki/WPD:New_Page> page is up to
date with example text and links, just like
the Getting Started<http://docs.webplatform.org/wiki/WPD:Getting_Started#Guides_to_creating_pages>page
which has a section that anticipates additional guides with a link to
the Creating API
Pages<http://docs.webplatform.org/wiki/WPD:Creating_API_pages>guide,
where all of the above is captured, if not tamed.
+SCott



On Tue, Nov 20, 2012 at 2:31 AM, Chris Mills <cmills@w3.org> wrote:

> This sounds pretty reasonable - thanks for sharing! Have you shared this
> information on any of the guideline pages yet?
>
> Best,
>
> Chris Mills
> Open standards evangelist, Opera Software
> W3C fellow
> Co-chair, web education community group, W3C
>
> * Author of "Practical CSS3: Develop and Design"
>   (
> http://my.opera.com/chrismills/blog/2012/07/12/practical-css3-my-book-is-finally-published
> )
> * The definitive guide to developing with the webplatform:
>   http://www.webplatform.org
>
> On 16 Nov 2012, at 18:36, Scott Rowe <scottrowe@google.com> wrote:
>
> > Thanks Julee and Mike!
> >
> > I'm sure everyone appreciates your careful and considerate assessment of
> these issues and the work you did to vet our assumptions. I certainly do!
> >
> > And a big THANKS to everyone involved in this effort!!!
> >
> > So at this point I'd like to mix a metaphor and sew up this thread!
> >
> > I believe we have achieved our original goal: removing enough of the
> obstacles to creating API pages to be able to continue with the work on new
> APIs. To review our decisions:
> >
> > We will continue to maintain a separation between the apis and dom
> namespaces.
> >
> > Considerations for the dom namespace may be taken up in a separate
> thread.
> >
> > The organization of the apis namespace will be as follows:
> >
> > apis
> > apis/<apilist>
> > apis/<apilist>/<apiObject>/<event>
> > apis/<apilist>/<apiObject>/<method>
> > apis/<apilist>/<apiObject>/<property>
> >
> > Note: we are eliminating all intermediate pages and object type
> identification from the URL. For example:
> >
> > apis/webrtc/MediaStreamTrackList/length
> >
> > While we are reasonably confident that there will be no collisions, such
> as  a property and a method of the same name, we are resolved to deal with
> these by inserting identifying labels, for example:
> >
> > apis/myapi/myAPI/void-property
> > apis/myapi/myAPI/void-method
> >
> > Such identifiers, however, are the exception, not the rule.
> >
> > Considerations for artifacts such as constants and events may be taken
> up in a separate thread. For now, these may be simply described in the
> summary sections of those properties and methods to which they belong.
> >
> > Okay, time for me to get cracking on the WebRTC API!
> >
> > +Scott
> >
> >
> >
> >
> >
> >
> > On Thu, Nov 15, 2012 at 2:48 PM, Julee Burdekin <julee@adobe.com> wrote:
> > Just to close the loop on the section "Moving all apis under dom",
> that's not exactly what was was proposed. It was more that a unified
> system, derived from the root browser objects, would more accurately
> represent that we are documenting one (reference) browser interface of the
> web platform. And then separate pages would list out the bundles that
> constitute the individual feature specs.
> >
> > But my primary concern is that we provide one place where the user
> arrives and "gets it", where the architecture is self-evident to the end
> user, and manifests the environment against which the user is coding. And
> we can provide this experience other ways, such as:
> >
> > * top-level pages diagram where things are and explain how to use the
> different sections
> > * apilist pages call out the objects from which they are derived
> > * root object pages mention which apis are derived from them
> >
> > Wherever possible, we should explain the gaps and provide bridges. Given
> that, I'm OK with moving ahead on the structure worked on on the
> WPD:Creating_API_pages <
> http://docs.webplatform.org/wiki/WPD:Creating_API_pages> page.
> >
> > Regards.
> >
> > J
> > ----------------------------
> > julee@adobe.com
> > @adobejulee
> >
> >
> > From:  Scott Rowe <scottrowe@google.com>
> > Date:  Wednesday, November 14, 2012 3:12 PM
> > To:  "public-webplatform@w3.org" <public-webplatform@w3.org>, Alex
> Komoroske <komoroske@google.com>
> > Subject:  Re: Creating API pages
> > Resent-From:  <public-webplatform@w3.org>
> > Resent-Date:  Wednesday, November 14, 2012 3:13 PM
> >
> >
> > 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 <
> https://dvcs.w3.org/hg/audio/raw-file/tip/webaudio/specification.html>,
> and are linked to the specific sections for easy reference.
> >
> > 4.3 <
> https://dvcs.w3.org/hg/audio/raw-file/tip/webaudio/specification.html#AudioSourceNode>
> AudioSourceNode
> > Listed as an "abstract" interface, has no documented properties or
> methods.
> >
> > 4.11 <
> https://dvcs.w3.org/hg/audio/raw-file/tip/webaudio/specification.html#MediaElementAudioSourceNode>
> MediaElementAudioSourceNode
> > Created in an Audiocontext, has no documented properties or methods.
> >
> > 4.14.1 <
> https://dvcs.w3.org/hg/audio/raw-file/tip/webaudio/specification.html#PannerNode-sub>
> PannerNode Constants
> > There's no API structure/path for constants.
> >
> > 4.18 <
> https://dvcs.w3.org/hg/audio/raw-file/tip/webaudio/specification.html#ChannelSplitterNode>
> ChannelSplitterNode and
> > 4.19 <
> https://dvcs.w3.org/hg/audio/raw-file/tip/webaudio/specification.html#ChannelMergerNode>
> ChannelMergerNode
> > Also have no documented properties or methods.
> >
> >
> > 4.24 <
> https://dvcs.w3.org/hg/audio/raw-file/tip/webaudio/specification.html#WaveTable>
> WaveTable and
> > 4.25 <
> https://dvcs.w3.org/hg/audio/raw-file/tip/webaudio/specification.html#MediaStreamAudioSourceNode>
> 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 <tel: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 <tel: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 <tel: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 <
> http://docs.webplatform.org/wiki/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
> >
> >
> >
> >
> >
> >
> >
> >
> >
> >
> >
> >
> >
> >
> >
> >
> >
> >
> >
> >
> >
> >
> >
> >
> >
> >
> >
> >
> >
> >
> >
> >
> >
> >
> >
> >
> >
> >
> >
>
>