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.willi...@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@lists.launchpad.net >>> Unsubscribe : https://launchpad.net/~openstack >>> More help : https://help.launchpad.net/ListHelp >> >> _______________________________________________ >> Mailing list: https://launchpad.net/~openstack >> Post to : openstack@lists.launchpad.net >> Unsubscribe : https://launchpad.net/~openstack >> More help : https://help.launchpad.net/ListHelp > > > _______________________________________________ > Mailing list: https://launchpad.net/~openstack > Post to : openstack@lists.launchpad.net > Unsubscribe : https://launchpad.net/~openstack > More help : https://help.launchpad.net/ListHelp _______________________________________________ Mailing list: https://launchpad.net/~openstack Post to : openstack@lists.launchpad.net Unsubscribe : https://launchpad.net/~openstack More help : https://help.launchpad.net/ListHelp
