Open Stack

I totally agree with Anne that the documentation in this "split up" format is very hard to both find and parse. It's not inaccurate, so much as it leaves a gaping hole in understanding what is and isn't available when you have 9+ documents to read and they're not really interlinked.

The effort I kicked off, but haven't had a lot of time to put into lately, to create a single unified portal/page for the API was an idea to address this weakness with the current structure.

I've created a github pages site to stub out how this might work - https://github.com/heckj/api-site-mock, with the generated site at http://heckj.github.com/api-site-mock/. It's very much a work in progress, which I hope to resume work on in a few weeks when I should be able to free up some additional time. I have documented my intention for the site's goals (https://github.com/heckj/api-site-mock/blob/master/GOALS.md) and design (https://github.com/heckj/api-site-mock/blob/master/DESIGN.md) - tl;dr, making a unified API directory for immediate web-based consumption (i.e. browser) along the lines of:
 * https://www.parse.com/docs/rest
 * https://dev.twitter.com/docs/api

If anyone else would be interested in collaborating on this site live to move it forward, I would be happy to add your accounts to directly push into the repository. And of course I'm happy to take pull requests.

-joe

On Dec 9, 2011, at 6:29 AM, Brian Waldon wrote:
> Hey Anne,
> 
> Great feedback! As for number 8, I think the nova-api team might be the best group to be tasked with reviewing code and documentation for any extensions proposed to Nova's codebase. And we can absolutely discuss this at the meeting today!
> 
> Brian
> 
> 
> On Dec 9, 2011, at 9:17 AM, Anne Gentle wrote:
> 
>> Hi everyone -
>> Overall I support this effort and have discussed it at length with the
>> Rackers working on it.
>> 
>> I'd really like to get feedback from everyone who thinks they'll
>> consume this type of information. I don't find it easy to use from an
>> API consumer's perspective, but it is an absolute must for the
>> projects to have a way to describe what parts of their API is an
>> extension.
>> 
>> Here are my suggestions on this first iteration, which I've talked to
>> Jorge about but also want to share with the list to get input.
>> 
>> 1. The header - at first it may confuse people since it's an OpenStack
>> header on a Rackspace domain name. I understand this convention was
>> chosen since you intend to give it over to OpenStack.
>> 2. In the header, I don't believe "Extensions Documentation" is the
>> correct label, probably just highlight "Documentation".
>> 3. I don't have a good sense of how readers will get to API
>> documentation from this page. With the API site also being worked on,
>> we'll need to find a good secondary nav for these types of sites.
>> 4. All of the links need to add an additional /content/ to the link to
>> avoid redirects.
>> 5. All of these "mini-docs" need to use a processing instruction or
>> pom directive to avoid the tiny chunking and only chunk at the chapter
>> level.
>> 6. I made some minor changes to the DocBook template so that people
>> can find the WADL normalizer tool.
>> 7. For the API site we're constructing, we're not yet sure how to
>> handle extensions for the API reference. Right now we need to fill in
>> a lot of reference information. Suggestions for integration are
>> welcomed.
>> 8. We need a discussion about who will review these extension
>> submissions and ensure they get built.
>> 
>> Based on the struggle to get these docs written, I also want to know
>> if you all find the templates useful and think you'll author these.
>> Any suggestions for the authoring side?
>> 
>> Brian, can we discuss at the nova-api meeting tomorrow at 3:00 CST in
>> #openstack-manuals as well? I'll also discuss at the Doc Team meeting
>> Monday 12/12 at 2:00 CST (20:00 UTC).
>> 
>> Thanks for all the work here. Let's iterate on this site.
>> Thanks,
>> Anne
>> 
>> On Thu, Dec 8, 2011 at 10:58 AM, Jorge Williams
>> <jorge.williams at rackspace.com> wrote:
>>> 
>>> Hi All,
>>> 
>>> I've started putting together a site to hold extension documentation.  You can see it here:
>>> 
>>> http://docs.rackspace.com/openstack-extensions/
>>> 
>>> The idea is to have a repository for all extensions, whether the extension is an OpenStack extension or a vendor specific extension. It makes sense to me that users can go to a central place to get extension docs regardless of where the extension came from or who wrote it, etc.  I'm putting this out as somewhat of a proposal with the hopes that we can roll this page into our own docs site. The site is *somewhat* automated. If you put the webhelp output that comes out of our docs tool chain, it will reach into the extension description sample for info about the extension and just roll it into the index page.  The idea is that we can have something like Jenkins spit out some webhelp to a directory and things will just work. The script that does this is written in perl though If anyone wants to take a stab at rewriting it in another language I'm all for it.  You can find it here:
>>> 
>>> https://github.com/RackerWilliams/extension-docs
>>> 
>>> What I'm really interested in right now is in getting good accurate docs for our extensions and putting them out there it a central place where people can see.  If you have info about a particular extension send it over.  There are pointers to doc templates at the bottom of the page and I know that I'll be working on documenting some of the extension that are currently out there for compute. BTW:  Take the compete  extensions that are out there at this very moment with a grain of salt  as some of these are still under development.
>>> 
>>> Finally, I've updated the extension guide based on feedback from folks.  You can find the guide here:
>>> 
>>> http://docs.rackspace.com/openstack-extensions/apix-intro/content/Overview.html
>>> 
>>> Note that the document is still a draft, so things are likely to change -- though I don't reckon dramatically. We're planning on having a wider discussion about extensions in the next nova-api team meeting on friday.
>>> 
>>> Questions?  Thoughts?
>>> 
>>> -jOrGe W.
>>> 
>>> 
>>> _______________________________________________
>>> Mailing list: https://launchpad.net/~openstack
>>> Post to     : openstack at lists.launchpad.net
>>> Unsubscribe : https://launchpad.net/~openstack
>>> More help   : https://help.launchpad.net/ListHelp
>> 
>> _______________________________________________
>> Mailing list: https://launchpad.net/~openstack
>> Post to     : openstack at lists.launchpad.net
>> Unsubscribe : https://launchpad.net/~openstack
>> More help   : https://help.launchpad.net/ListHelp
> 
> 
> _______________________________________________
> Mailing list: https://launchpad.net/~openstack
> Post to     : openstack at lists.launchpad.net
> Unsubscribe : https://launchpad.net/~openstack
> More help   : https://help.launchpad.net/ListHelp