Open Stack

On Tue, Aug 4, 2015 at 9:40 AM, Anne Gentle <annegentle at justwriteclick.com>
wrote:

>
>
> On Tue, Aug 4, 2015 at 7:48 AM, Sean Dague <sean at dague.net> wrote:
>
>> On the plane home from the Nova midcycle meetup I spent a chunk of time
>> reading our API docs that are now in tree:
>>
>> https://github.com/openstack/nova/blob/master/doc/source/v2/2.0_server_concepts.rst
>> and it got me concerned that documentation improvements don't seem to be
>> the top priority on the API infrastructure side.
>>
>> The API concept guide is a really useful (though currently horribly out
>> of date) document for someone trying to use the Nova API without reading
>> all the Nova code. I feel like without that kind of big picture view,
>> the Nova API is quite hard to sort out.
>>
>> I'd like to get updating that much higher up the priority list for the
>> API subteam. I realize there is this large json home patch series out
>> there to add new hotness to the API, but I feel like json home is
>> premature until we've got a concept picture of the Nova API in
>> documentation.
>>
>> How do we get this ball rolling? Who's up for helping? How do we get the
>> concept guide back onto developer.openstack.org once it's not horribly
>> out of date?
>>
>> I don't feel like I've got a plan yet in my head, but I'd really like to
>> get one developed over the next couple of weeks so that we can actually
>> make some real progress here. So who is up for helping, and what format
>> this plan will take, are the key bits.
>>
>
>
> I'm up for helping, and it's related to our work on
> http://specs.openstack.org/openstack/docs-specs/specs/liberty/api-site.html,
> because ideally we'll build the API dev guides on developer.openstack.org
> .
>
> Can you use the plan we've got now and help out? What would you adjust,
> the "narrative" portion publishing?
>

Hi all,

I've adjusted the plan a bit here: https://review.openstack.org/#/c/209669/

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.

Thanks,
Anne




> Thanks,
> Anne
>
>
>>
>>         -Sean
>>
>> --
>> Sean Dague
>> http://dague.net
>>
>> __________________________________________________________________________
>> OpenStack Development Mailing List (not for usage questions)
>> Unsubscribe:
>> OpenStack-dev-request at lists.openstack.org?subject:unsubscribe
>> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
>>
>
>
>
> --
> Anne Gentle
> Rackspace
> Principal Engineer
> www.justwriteclick.com
>



-- 
Anne Gentle
Rackspace
Principal Engineer
www.justwriteclick.com
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-dev/attachments/20150807/aec300f0/attachment.html>