Thanks, Jay. I usually try to be more careful with the API names, so thanks for clarifying.<br><br>Any other PTLs with needs or opinions here? <br><br>I think the landing page containing Draft API docs looks something like the attached mockup, let me know your feedback.<br>

<br>Jay, you're the only PTL using Google Docs for feedback, others have used the doc comments system, Disqus. I can set up doc comments feeds specifically for RFC periods on particular specs, though your Google Docs approach works fine also. It would be nice to standardize but I also like that Google docs lets you click "Resolved" on a comment. <br>

<br>I have the ability to make DRAFT in big red letters on the output. I could also put RFC as a watermark on the page during the RFC period in addition to the DRAFT in each page. <br><br>I mostly want to ensure easy access so that the draft APIs get plenty of comments and reviews.<br>


<br>Thanks,<br>Anne<br><br><div style="margin: 2em 0pt;" name="sig_d41d8cd98f"><div style="padding: 5px; font-size: 11px; color: rgb(102, 102, 102); font-family: sans-serif;">
<strong>Anne Gentle</strong>
 <br>
<a href="mailto:anne@openstack.org" target="_blank">anne@openstack.org</a><br>
<div style="font-size: 10px;">
<a href="http://justwriteclick.com/" target="_blank">my blog</a> |
<a href="http://xmlpress.net/publications/conversation-community/" target="_blank">my book</a> |
<a href="http://www.linkedin.com/in/annegentle" target="_blank"><span>LinkedIn</span></a> | <a href="http://del.icio.us/annegentle" target="_blank">Delicious</a> |
 <a href="http://twitter.com/annegentle" target="_blank">Twitter</a>

</div></div></div><div class="gmail_quote">On Wed, Nov 9, 2011 at 8:41 AM, Jay Pipes <span dir="ltr"><<a href="mailto:jaypipes@gmail.com" target="_blank">jaypipes@gmail.com</a>></span> wrote:<br><blockquote class="gmail_quote" style="margin: 0pt 0pt 0pt 0.8ex; border-left: 1px solid rgb(204, 204, 204); padding-left: 1ex;">


<div>On Tue, Nov 8, 2011 at 5:54 PM, Anne Gentle <<a href="mailto:anne@openstack.org" target="_blank">anne@openstack.org</a>> wrote:<br>
> Hi all -<br>
><br>
> We have three projects that need to have draft API docs (for a new API<br>
> version) published for feedback and consumption during the Essex timeframe.<br>
> (Quantum 1.0>1.1, Glance 1.1>2.0, and Nova 1.1>2.1)<br>
<br>
</div>Small, but important correction: It is not the Quantum, Glance API or<br>
the Nova API, but the OpenStack Networks API, Images API and Compute<br>
API :)<br>
<br>
I raised this issue at the last design summit and have continued to<br>
raise it on the mailing list in various discussions, but I think it is<br>
important to state that how an API evolves can and should be separated<br>
from a reference implementation of that API.<br>
<br>
There's a reason why the word "Glance" doesn't appear anywhere in the<br>
proposed Images API 2.0 drafts.<br>
<div><br>
> I'd like to get ideas about where those should be published and some of the<br>
> requirements around their draft status.<br>
<br>
</div>So... are we talking about when/where to publish the proposed draft<br>
spec AFTER it has gone through an RFC period and gotten feedback? Or<br>
are we talking about codifying the way we go about getting feedback<br>
during an RFC period on a proposed API?<br>
<br>
I kind of like the way that commenting on Google Docs has worked for<br>
the Images API 2.0 proposed drafts. It's easy enough to comment on a<br>
block of the document and respond -- and emails get sent out notifying<br>
you of new or updated comments. We got feedback from 12 individuals<br>
via comments on the Google Doc, and through an iterative process, have<br>
responded to those comments and/or incorporated the feedback back into<br>
the proposal.<br>
<br>
I'm in the process of completing the final requested changes to the<br>
second draft document and was then planning to email the mailing list<br>
with a "OK, here is the final draft. Last chance to comment before we<br>
begin implementing it in Glance" post. I'd like to work with you on<br>
taking the proposed draft Google Doc into the main<br>
<a href="http://docs.openstack.org/api/" target="_blank">http://docs.openstack.org/api/</a> site.<br>
<br>
The current 1.x API is here:<br>
<br>
<a href="http://docs.openstack.org/api/openstack-image-service/1.0/content/" target="_blank">http://docs.openstack.org/api/openstack-image-service/1.0/content/</a><br>
<br>
I'd love it if we could put the final 2.0 proposal here:<br>
<br>
<a href="http://docs.openstack.org/api/openstack-image-service/2.0/content/" target="_blank">http://docs.openstack.org/api/openstack-image-service/2.0/content/</a><br>
<br>
With a link to it from the main API area, noting that the 2.0 API is<br>
in DRAFT mode until X date -- to be determined later?<br>
<div><br>
> Is there a need for special treatment for "RFC" vs. "Draft" designations<br>
> such as RFC for a certain time period, then Draft?<br>
<br>
</div>I think the RFC period should run by the respective PTL for the<br>
project and then a DRAFT mode indicates it is in the period AFTER the<br>
RFC time and before the proposed API is fully implemented by a<br>
project. That work for you?<br>
<div><br>
> Do these need drafts need to be published to <a href="http://docs.openstack.org/api" target="_blank">docs.openstack.org/api</a>, or is<br>
> that site for "final" APIs for end-users?<br>
<br>
</div>See above. I think having the DRAFT on the API site would be very<br>
helpful (again, after the RFC period closes)<br>
<div><br>
> I envision introducing more<br>
> confusion than is already present if we publish them side-by-side.<br>
> Do these API drafts need their own site for the RFC/Draft period, such as<br>
> <a href="http://api.openstack.org/drafts" target="_blank">api.openstack.org/drafts</a>?<br>
<br>
</div>No, I think just clearly marking the draft API with DRAFT in big red<br>
letters is good :)<br>
<br>
Cheers, and thanks for caring about this subject that's close to my heart!<br>
<font color="#888888">-jay<br>
</font></blockquote></div><br>