Open Stack

Some thoughts (and research citations, Look.Out. below.)

On Thu, Nov 8, 2012 at 6:07 AM, Sean Dague <sdague at linux.vnet.ibm.com> wrote:
> On 11/07/2012 05:09 PM, Anne Gentle wrote:
> <snip>
>
>>
>> So, api.openstack.org was originally an experiment to get all the
>> extensions in one place, but I do believe it has met that objective
>> and now it's time to stop confusing people with "what's the difference
>> between docs.openstack.org/api and api.openstack.org? So that's the
>> first step - get a more descriptive landing page on api.openstack.org
>> rather than a long list of calls.
>
>
> Honestly, having spent a bunch of time with api.openstack.org and the
> os-compute-api manual recently, I'm not sure we're doing ourselves any
> favors but having api.openstack.org as a seperate thing.

Agreed - the purest future vision is to embed the WADLs that build
api.openstack.org into the os-compute-api manual itself for one source
of truth and two ways of viewing it.

The long reference listing is helpful I believe (Joe Heck originally
requested it) in addition to the narrative guides. We just need to
blend the source more strictly and that takes work.

> The os-compute-api manual is really good (I'll assume the same of the
> others), really complete, and having something else that people tend to get
> stuck on first which isn't anywhere nearly as good, seems counter
> productive.

Yep, need to figure out where people navigate around to. This week we
updated the Google Analytics code for docs.openstack.org and
wiki.openstack.org and other sites so we can figure out where visitors
go to. I expect we'll have hints with data not opinions in a month or
so.

>
>>> api.openstack.org/python => Would be a place for examples of using the
>>> Python bindings API exposed by python-*client packages. Would NOT be a
>>> place for examples of using the CLI tools, though... that documentation
>>> would/should live in the administrator's guide IMHO
>>
>>
>> We do have a new-ish CLI guide [1] for all the OpenStack CLIs linked
>> from the docs landing page. So I agree here and the content is shared
>> with the Compute Admin Manual too.
>
>
>>> So, for instance, api.openstack.org/python/compute would show examples
>>> like this:
>>>
>>> from novaclient.v1_1 import client
>>> c = client.Client(USER, PASS, TENANT, AUTH_URL, service_type="compute")
>>>
>>> for s in c.servers.find(host="myhost"):
>>>      print s.id, s.name
>>>
>>> But not examples like this:
>>>
>>> $> nova list --host=myhost
>>
>>
>> I always like for URLs to self-describe what's going on. Not sure if
>> we have to get this fine a point on it but I'll certainly take it into
>> consideration for the api site work. The work so far is:
>>
>> -Track bugs against api.openstack.org at a new Launchpad project,
>> openstack-api-site.
>> -Change CI Infrastructure builds to build from a new
>> openstack/api-site repo on GitHub.
>>
>> What'll happen next is to change the landing page at api.openstack.org
>> so the long listing is a sub-page, api.openstack.org/api-ref.html.
>> Then I'll also redirect from docs.openstack.org/api to
>> api.openstack.org. I think the landing page is going to be:
>>
>> API Reference
>> API Specs
>> SDKs
>>
>> Then when you click through to API Reference we can start to build out
>> all these examples and finish out the blueprint to bring in all the
>> tested Compute API samples.
>>
>> I don't know if we have to do /python/ /http/ /php/ /java/ sub
>> directories but that might be fine, what do others think of Jay's
>> examples?
>
>
> Having a place for examples is a great idea. That should really support user
> generated content though, I think git ends up being too high a barrier on
> that one, because the folks that you want those examples from are often not
> going to be developers.

Ah, my favorite research topic, user- and community-generated content.
Check out this blog post on user-generated content for API docs
specifically.

http://blog.ninlabs.com/2012/05/crowd-documentation/

A couple of notes of caution from their research:
- After 2 years only 30% coverage for API calls for Android. The speed
of gaining coverage is too slow if we wait for the crowd - we need to
throw more resources at this problem I believe.
- We would have gains from funneling and collecting samples though -
and this is where I believe the discipline and tracking of Launchpad
and Git processes come in.

> I've worked with sgml on and off for a decade, and it still makes me
> confused. :) I can imagine that it's really hard for end users where great
> examples could come from.

Is it WADL that is troubling to you? I too find it unwieldy sometimes.
I do have discussions with devs here at Rackspace to design a web form
that would output a WADL complete with examples - to me this is the
way we could collect examples and get more coverage. Is anyone
interested in designing this? What a cool side project if you're up
for it. Want a blueprint? I can write it up.

Another one of the visions for api.openstack.org was to have a "Try it
out" webform for each call that would send calls to TryStack. I've had
interested grad students working on JStack, but no actual project
completed yet.

Thoughts and comments welcomed on my favorite topic!

Anne

>> I'd also like to get much more practical documentation than spec
>> documentation. Where do all these code samples come from? The amount
>> of work to integrate hundreds of new Compute code samples is a long
>> list, we'll just piece through it, but do other APIs have that many
>> tested examples (hundreds)? Let me know how to find 'em and I'll find
>> a way to integrate them and be smart about it. I haven't found many
>> people willing to do the tedious API doc work so if you're even
>> thinking of helping out, please do so!
>>
>> Thanks for keeping on it you all!
>> Anne
>>
>>> We could further have examples for any other language bindings follow
>>> the same kind of sitemap structure.
>>>
>>> Thoughts?
>>> -jay
>>
>>
>> [1] http://docs.openstack.org/cli/quick-start/content/index.html
>>
>> _______________________________________________
>> OpenStack-dev mailing list
>> OpenStack-dev at lists.openstack.org
>> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
>>
>
>
> --
> Sean Dague
> IBM Linux Technology Center
> email: sdague at linux.vnet.ibm.com
> alt-email: sldague at us.ibm.com
>
>
>
> _______________________________________________
> OpenStack-dev mailing list
> OpenStack-dev at lists.openstack.org
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev