openstack team mailing list archive

[Doug Hellmann <doug.hellmann@xxxxxxxxxxxxx>]

+1 to separating specifications from documentation for API users

On Mon, Jul 30, 2012 at 1:09 PM, Anne Gentle <anne@xxxxxxxxxxxxx> wrote:

> 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
>
> _______________________________________________
> Mailing list: https://launchpad.net/~openstack
> Post to     : openstack@xxxxxxxxxxxxxxxxxxx
> Unsubscribe : https://launchpad.net/~openstack
> More help   : https://help.launchpad.net/ListHelp
>