Re: Creating API pages

Hi Scott,

Thanks for writing this up!

The organization is confusing me a bit since it bounces back and forth
between between critiquing the current setup, proposing changes, and
describing how to practically accomplish things in the current set-up (I
think? It may describe how to accomplish things in the hypothetical
future). Is there a crisp summary of the changes you propose?

Also, note that your point about the Applies_to field not working for
things like apis/indexedDB/IDBCursor is incorrect--it was actually just a
caching problem. After you update the applies_to field, you often need to
do a hard refresh (Edit > Refresh from within the page) of the page where
you want it to show up.  We should document this somewhere, perhaps next to
the Applies_to field itself.

--Alex



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