Open Stack

Hi Anne

On 10/30/2012 08:43 AM, Anne Gentle wrote:
> I think there's a potential for slight worsening of the API docs
> situation ... but I'd like to hear statements pro and con introducing
> an API that we don't document into the OpenStack ecosystem. I really
> do want to understand this better and it's important that I do
> understand it from many perspectives, not just my "Anne from docland"
> view.
>
> About our API docs current state - there are about 30 bugs logged [1],
> some of the docs are specs, some are not, and API docs constantly need
> care and feeding, something we're not resourcing greatly. My
> understanding is there are about 25 API writers at Amazon, and in our
> open API world, no one is specifically tasked with documenting the
> OpenStack APIs (that I know of). Many of my conversations about docs
> are more with QA folks who want a spec to test against. Users of APIs,
> they seem to be managing, but I'm sure they'd also like more docs.
>
> So what I'd like to hear is not just that we need tests and
> development for API additions, but docs as well. What do you all
> envision as the doc plan for this type of API usage for OpenStack
> deployers?

The completed REST API for Heat will be about 12 calls, which makes it 
one of the smaller APIs; about the same size as Glance. We can 
absolutely commit to documenting these and any additional API that gets 
added.

Another documenting task is the (JSON based) template format.

For the Amazon resource types we can refer users to the Amazon docs and 
clearly document the few places where Heat differs.

For OpenStack resource types the aim will be to map as closely as 
possible to the underlying OpenStack services, so documenting will be 
copypaste, with the potential of being autogenerated.

cheers