Re: Creating API pages

Thanks PhistucK - my thoughts in-line...
+Scott



On Wed, Nov 14, 2012 at 11:53 PM, PhistucK <phistuck@gmail.com> wrote:

> See my comments inline.
>
> ☆*PhistucK*
>
>
>
> On Thu, Nov 15, 2012 at 1:12 AM, 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>
>>
>>
> Great!
> Just to be clear. This would be the final URL -
> apis/webaudio/MediaStreamAudioNode/createMediaStreamSource
> And not this -
> apis/webaudio/MediaStreamAudioNode/createMediaStreamSource-method
>
> Right?
>

Right - that's my understanding.



>
>
>
>> 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.
>>
>>
> Creating a page for every constant seems like a real overkill.
> I am not sure if this is technically possible, but I propose we add a
> constant section on every API Object template. Instead of the "Applies
> to..." approach, we can define a "Possible value" approach. Draw the value
> from the API Object page.
>
> Example -
> dom/Node has a (special) constants section that is not drawn from
> anywhere, it is inline. Every constant has a category (node types) a name,
> a value, a type and a summary.
> dom/Node/nodeType has a possible values section/field with the following
> value - dom/Node#ELEMENT_NODE, dom/Node#TEXT_NODE (and so on), or a
> category of constants - dom/Node#node-type-constants.
>
> Creating pages for every constant and adding all of the properties/methods
> (parameters? sounds complicated. Example - document.evaluate)/objects it
> applies to sounds like a real pollution.
>

Yes, I share your concerns. My first thought was, how often does a constant
need to be reused within a given api object, and how much benefit to the
user (us) is there in building an infrastructure to support this case? In
short, is this really necessary? Sure, it would be nice to achieve an
elegant solution here, but is it a priority? To tell you the truth, I'm not
convinced.



>
>
>
>> *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.
>>
>
> Note that properties can raise exceptions as well when set, I believe.
>
> While I agree that common exceptions should have their own pages, I
> propose a model similar to what I proposed for constants, for exceptions.
> Instead of adding all of the methods to an "Applies to..." field, fetch
> the exception from the method page and not the other way around.
> And in the case of rarely used exceptions (or maybe only exceptions that
> are used in a single method), add them inline in a special constant section.
>

As with constants, I'm not convinced that providing for an elegant UI for
the reuse of exceptions is a high priority. But I think we should continue
noodling on the subject - good mental exercise!



>
>
>> *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.
>>
>
> I am also against this, but not strongly. For the same reason as below.
> However, an argument in favor is that it is kind of hard to decide whether
> something should be added to dom/ or to apis/.
>

Yeah, dude, I'm with you! We have to draw the line somewhere though.



>
>
>>
>> *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.
>>
>>
> Listings are very useful wherever they are. I am also against removing
> listing pages. The more, the merrier.
>

Well of course I agree. The close approximation - that is, within the apis
namespace, as in apis/<apilisting> - provides a level of meta data,
certainly within the current URL-as-navigation methodology, but also long
term where eventually we collate all of the page meta data into a taxonomy
and use it to serve up search results.



>
>
>> *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.>?
>>
>>
> apilist is useful for context. However, how many developers actually look
> at the URL of the documentation? I know I do, but I think most do not.
> I am against removing the apilist part, but not strongly, because I
> realize it is not that useful for everyone.
>

Agreed. The URL structure is ultimately a facility for locating - that is,
for us when creating articles. It is less important as a navigation
facility for users *once we get our search house in order*. But presently
search is so crappy that users can't even use it. While it's embarrassing
to force the users to divine the structure and find articles through the
URLs, it's pretty much all we've got right now.



>
>
>> 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 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<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
>>>>>>>
>>>>>>>
>>>>>>
>>>>>
>>>>
>>>
>>
>