openstack team mailing list archive

[Anne Gentle <anne@xxxxxxxxxxxxx>]

Hi again all, your friendly doc coordinator here.

I'd like to get a big push towards documenting reality instead of
relying only on the specs stored in the compute-api repository. As an
example, recently a Rackspace writer inserted min_count and max_count
to the compute-api repository but the change was reversed after a
request by Brian Waldon and Jorge Williams to leave the spec as-is. I
agree that the spec has value but I believe we need to push towards
reality and creating developer guides.

So what I'd like to propose here is that we govern these repos as
specs and change the titles of those documents to API specification:

compute-api
image-api
identity-api
object-api
netconn-api

At the same time, we'd start new "developer guides" in the
openstack-manuals repository that document reality. We can track the
work needed through the openstack-manuals bug and blueprint system.

I went up to Brian Aker after his keynote at OSCon seeking contacts at
HP who are interested in doing this type of work, and I have started
some one-on-one meetings, but I'd like to find more interested
collaborators. Anyone at Rightscale or Enstratus interested? Also are
there other API implementers who are experts in how the APIs really
work? Please join in finding the right solution here.

Does this proposal sound like a workable solution? Any tweaks or other
suggestions?

Thanks,
Anne