Re: Creating API pages

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#Audio
SourceNode> 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#Media
ElementAudioSourceNode> 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#Panne
rNode-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#Chann
elSplitterNode> ChannelSplitterNode and
4.19 
<https://dvcs.w3.org/hg/audio/raw-file/tip/webaudio/specification.html#Chann
elMergerNode> ChannelMergerNode
Also have no documented properties or methods.


4.24 
<https://dvcs.w3.org/hg/audio/raw-file/tip/webaudio/specification.html#WaveT
able> WaveTable and
4.25 
<https://dvcs.w3.org/hg/audio/raw-file/tip/webaudio/specification.html#Media
StreamAudioSourceNode> 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