Open Stack

On 08/07/13 23:39, Anne Gentle wrote:
> Thanks for the summary Tom.
> 
> 
> On Sun, Jul 7, 2013 at 5:59 PM, Tom Fifield <tom at openstack.org
> <mailto:tom at openstack.org>> wrote:
> 
>     Sorry all - this accidentally dropped off the list for a few replies
>     before we realised.
> 
>     Here's the summary:
>     Nick asked:
> 
>     I was suggesting that the nova code should generate the WADL when it
>     generates the sample files.  That is, or is not, what happens now?
> 
>     Anne replied:
> 
>     The items that are auto-generated are the requests and responses in
>     JSON and XML. The WADL is hand written to point to those generated
>     files.
> 
>     Nick asked:
> 
>     can we have that same process also generate the WADL?  And would it
>     solve the problem of missing pieces?
> 
>     Anne replied:
> 
>     We can ask if the validating step can generate docs also. That would
>     be a good step towards completeness of the API doc.
> 
>     On this basis, I have created a new blueprint:
> 
>     https://blueprints.launchpad.__net/openstack-manuals/+spec/__autogenerate-api-reference
>     <https://blueprints.launchpad.net/openstack-manuals/+spec/autogenerate-api-reference>
> 
>     to track the investigation
> 
> 
> I don't think we need a blueprint just to investigate, do you? And the
> blueprint would live in another project I suppose? 

Blueprints let the general community know what we're up to - an
important part of our Open Design process, I believe :) It can be moved
anywhere that is deemed appropriate, noting for example that api-site on
launchpad doesn't have blueprints enabled right now.

> I also want to note that the QA list is having a similar discussion
> about test artifacts and docs. [1] and Sean Dague is just kind of tired
> of the lack of coordination across 9 APIs... probably not summarizing it
> well enough, but that's kind of how I'm feeling too, that we could try
> to get one project in line and then 8 others would have to buy into the
> approach. We have to serve users first and foremost, so for me, I'd
> prefer to stay in the land of user docs and not encroach into writing
> specs. Thoughts on toeing that line or drawing it?

An API Reference is absolutely a user doc.

Unless, that is, all of our recent conversation around increasing the
prominence of the 'application developer' type of user was just lip service?

We'd hope that the first thing that happens after nova APIv3 is
released, on api.openstack.org, is that all of the SDK developers come
along and update their kits with the latest version.

If this isn't possible for these people to do, due to a lack of
documentation, we won't get adoption of the OpenStack API, and we will
fail our mission.

> Anne
>  
> 
> 1. http://lists.openstack.org/pipermail/openstack-qa/2013-July/000599.html
> 
> 
>     Regards,
> 
>     Tom
> 
> 
> 
>     On 08/07/13 04:48, Anne Gentle wrote:
> 
> 
> 
>         Anne Gentle
>         Content Stacker
>         anne at openstack.org <mailto:anne at openstack.org>
>         <mailto:anne at openstack.org <mailto:anne at openstack.org>>
> 
> 
> 
>         On Jul 7, 2013, at 2:19 PM, Nick Chase <nchase at mirantis.com
>         <mailto:nchase at mirantis.com>
>         <mailto:nchase at mirantis.com <mailto:nchase at mirantis.com>>> wrote:
> 
>             Right, ok, so what I'm saying is, can we have that same
>             process also
>             generate the WADL?  And would it solve the problem of
>             missing pieces?
> 
> 
> 
>         As far as I can tell no one has asked about docs until now. So
>         we can
>         ask if the validating step can generate docs also. That would be
>         a good
>         step towards completeness of the API doc.
> 
>             On Sun, Jul 7, 2013 at 2:12 PM, Anne Gentle
>             <annegentle at justwriteclick.com
>             <mailto:annegentle at justwriteclick.com>
>             <mailto:annegentle at __justwriteclick.com
>             <mailto:annegentle at justwriteclick.com>>>
> 
>             wrote:
> 
> 
> 
>                 Anne Gentle
>                 Content Stacker
>                 anne at openstack.org <mailto:anne at openstack.org>
>             <mailto:anne at openstack.org <mailto:anne at openstack.org>>
> 
> 
> 
>                 On Jul 7, 2013, at 1:56 PM, Nick Chase
>             <nchase at mirantis.com <mailto:nchase at mirantis.com>
>                 <mailto:nchase at mirantis.com
>             <mailto:nchase at mirantis.com>>> wrote:
> 
> 
> 
> 
>                     On Sat, Jul 6, 2013 at 7:39 PM, Tom Fifield
>                 <tom at openstack.org <mailto:tom at openstack.org>
>                     <mailto:tom at openstack.org
>                 <mailto:tom at openstack.org>>> wrote:
> 
> 
>                         However, in this case, since we're publishing
>                 the definitive
>                         reference
>                         on something that can actually be tested to be
>                 complete - we
>                         should have
>                         higher standards. Right now, the truth is, we
>                 have no idea
>                         how complete
>                         the API reference is. The only way we have to
>                 find out is to
>                         sit down
>                         with a beverage of some description and
>                 methodically work
>                         through a ton
>                         of code and a ton of WADL.
> 
> 
>                     OK, this is where I got confused; I was suggesting
>                 that the nova
>                     code
>                     should generate the WADL when it generates the
>                 sample files.
>                      That is,
>                     or is not, what happens now?
> 
> 
>                 The items that are auto-generated are the requests and
>             responses
>                 in JSON and XML. The WADL is hand written to point to those
>                 generated files.
> 
>                     ----  Nick
> 
> 
> 
> 
> 
> 
> 
> -- 
> Anne Gentle
> annegentle at justwriteclick.com <mailto:annegentle at justwriteclick.com>