<div dir="ltr"><br><div class="gmail_extra"><br><div class="gmail_quote">On Tue, Aug 4, 2015 at 9:40 AM, Anne Gentle <span dir="ltr"><<a href="mailto:annegentle@justwriteclick.com" target="_blank">annegentle@justwriteclick.com</a>></span> wrote:<br><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex"><div dir="ltr"><br><div class="gmail_extra"><br><div class="gmail_quote"><span class="">On Tue, Aug 4, 2015 at 7:48 AM, Sean Dague <span dir="ltr"><<a href="mailto:sean@dague.net" target="_blank">sean@dague.net</a>></span> wrote:<br><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">On the plane home from the Nova midcycle meetup I spent a chunk of time<br>
reading our API docs that are now in tree:<br>
<a href="https://github.com/openstack/nova/blob/master/doc/source/v2/2.0_server_concepts.rst" rel="noreferrer" target="_blank">https://github.com/openstack/nova/blob/master/doc/source/v2/2.0_server_concepts.rst</a><br>
and it got me concerned that documentation improvements don't seem to be<br>
the top priority on the API infrastructure side.<br>
<br>
The API concept guide is a really useful (though currently horribly out<br>
of date) document for someone trying to use the Nova API without reading<br>
all the Nova code. I feel like without that kind of big picture view,<br>
the Nova API is quite hard to sort out.<br>
<br>
I'd like to get updating that much higher up the priority list for the<br>
API subteam. I realize there is this large json home patch series out<br>
there to add new hotness to the API, but I feel like json home is<br>
premature until we've got a concept picture of the Nova API in<br>
documentation.<br>
<br>
How do we get this ball rolling? Who's up for helping? How do we get the<br>
concept guide back onto <a href="http://developer.openstack.org" rel="noreferrer" target="_blank">developer.openstack.org</a> once it's not horribly<br>
out of date?<br>
<br>
I don't feel like I've got a plan yet in my head, but I'd really like to<br>
get one developed over the next couple of weeks so that we can actually<br>
make some real progress here. So who is up for helping, and what format<br>
this plan will take, are the key bits.<br></blockquote><div><br></div><div><br></div></span><div>I'm up for helping, and it's related to our work on <a href="http://specs.openstack.org/openstack/docs-specs/specs/liberty/api-site.html" target="_blank">http://specs.openstack.org/openstack/docs-specs/specs/liberty/api-site.html</a>, because ideally we'll build the API dev guides on <a href="http://developer.openstack.org" target="_blank">developer.openstack.org</a>. </div><div><br></div><div>Can you use the plan we've got now and help out? What would you adjust, the "narrative" portion publishing? </div></div></div></div></blockquote><div><br></div><div>Hi all, </div><div><br></div><div>I've adjusted the plan a bit here: <a href="https://review.openstack.org/#/c/209669/">https://review.openstack.org/#/c/209669/</a></div><div><br></div><div>Basically we want to ensure we can publish great conceptual guides to ensure users understand the capabilities with our APIs. Plus, we want to support the microversion shifts and provide more writing enablement! So, feel free to review the revised plan, and please do write all you like about your API while we work hard on the reference information automation in parallel.</div><div><br></div><div>Thanks,</div><div>Anne</div><div><br></div><div> </div><div> </div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex"><div dir="ltr"><div class="gmail_extra"><div class="gmail_quote"><div>Thanks,</div><div>Anne </div><span class=""><div> </div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">
<span><font color="#888888"><br>
-Sean<br>
<br>
--<br>
Sean Dague<br>
<a href="http://dague.net" rel="noreferrer" target="_blank">http://dague.net</a><br>
<br>
__________________________________________________________________________<br>
OpenStack Development Mailing List (not for usage questions)<br>
Unsubscribe: <a href="http://OpenStack-dev-request@lists.openstack.org?subject:unsubscribe" rel="noreferrer" target="_blank">OpenStack-dev-request@lists.openstack.org?subject:unsubscribe</a><br>
<a href="http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev" rel="noreferrer" target="_blank">http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev</a><br>
</font></span></blockquote></span></div><span class="HOEnZb"><font color="#888888"><br><br clear="all"><div><br></div>-- <br><div><div dir="ltr"><div>Anne Gentle</div><div>Rackspace</div><div>Principal Engineer</div><div><a href="http://www.justwriteclick.com" target="_blank">www.justwriteclick.com</a></div></div></div>
</font></span></div></div>
</blockquote></div><br><br clear="all"><div><br></div>-- <br><div class="gmail_signature"><div dir="ltr"><div>Anne Gentle</div><div>Rackspace</div><div>Principal Engineer</div><div><a href="http://www.justwriteclick.com" target="_blank">www.justwriteclick.com</a></div></div></div>
</div></div>