+1 to separating specifications from documentation for API users<br><br><div class="gmail_quote">On Mon, Jul 30, 2012 at 1:09 PM, Anne Gentle <span dir="ltr"><<a href="mailto:anne@openstack.org" target="_blank">anne@openstack.org</a>></span> wrote:<br>
<blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">Hi again all, your friendly doc coordinator here.<br>
<br>
I'd like to get a big push towards documenting reality instead of<br>
relying only on the specs stored in the compute-api repository. As an<br>
example, recently a Rackspace writer inserted min_count and max_count<br>
to the compute-api repository but the change was reversed after a<br>
request by Brian Waldon and Jorge Williams to leave the spec as-is. I<br>
agree that the spec has value but I believe we need to push towards<br>
reality and creating developer guides.<br>
<br>
So what I'd like to propose here is that we govern these repos as<br>
specs and change the titles of those documents to API specification:<br>
<br>
compute-api<br>
image-api<br>
identity-api<br>
object-api<br>
netconn-api<br>
<br>
At the same time, we'd start new "developer guides" in the<br>
openstack-manuals repository that document reality. We can track the<br>
work needed through the openstack-manuals bug and blueprint system.<br>
<br>
I went up to Brian Aker after his keynote at OSCon seeking contacts at<br>
HP who are interested in doing this type of work, and I have started<br>
some one-on-one meetings, but I'd like to find more interested<br>
collaborators. Anyone at Rightscale or Enstratus interested? Also are<br>
there other API implementers who are experts in how the APIs really<br>
work? Please join in finding the right solution here.<br>
<br>
Does this proposal sound like a workable solution? Any tweaks or other<br>
suggestions?<br>
<br>
Thanks,<br>
Anne<br>
<br>
_______________________________________________<br>
Mailing list: <a href="https://launchpad.net/~openstack" target="_blank">https://launchpad.net/~openstack</a><br>
Post to     : <a href="mailto:openstack@lists.launchpad.net">openstack@lists.launchpad.net</a><br>
Unsubscribe : <a href="https://launchpad.net/~openstack" target="_blank">https://launchpad.net/~openstack</a><br>
More help   : <a href="https://help.launchpad.net/ListHelp" target="_blank">https://help.launchpad.net/ListHelp</a><br>
</blockquote></div><br>