openstack team mailing list archive

[Jay Pipes <jaypipes@xxxxxxxxx>]

On Thu, 2011-11-10 at 13:22 -0600, Anne Gentle wrote:
> Thanks, Jay. I usually try to be more careful with the API names, so
> thanks for clarifying.

Sorry if I sounded patronizing there.. didn't mean to be.

> I think the landing page containing Draft API docs looks something
> like the attached mockup, let me know your feedback.

Looks great to me.

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

Yeah, I like the fact that you can comment on a specific block of the
proposal as well, instead of all in one list of comments at the bottom
of a page. Also, yes, the Resolved comment feature is very nice for this
kind of iterative feedback.

That said, however, if it is your wish to do all draft API proposals
using a single system, so that it is easier for you to maintain, I will
bend to your will :)

> 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. 
> 
> I mostly want to ensure easy access so that the draft APIs get plenty
> of comments and reviews.

Yep, me too. :)

-jay