Joe, I fully support your effort in creating a central reference page like the one on your mock...and in fact I'm working with some of the doc tools folks to help make that happen.
I think that the extension site contains different kind of docs for different audience -- made up of implementors and language binding builders. The need there is to evaluate exactly how an individual extension modifies the core -- you can certainly build a centralized reference page from the info contained there in. -jOrGe W. -----Original Message----- From: Joseph Heck <he...@mac.com> Date: Fri, 9 Dec 2011 11:47:27 -0800 To: Brian Waldon <brian.wal...@rackspace.com> Cc: "openstack@lists.launchpad.net (openstack@lists.launchpad.net)" <openstack@lists.launchpad.net> Subject: Re: [Openstack] Extension Documentation >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/Overv >>>>iew.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 _______________________________________________ Mailing list: https://launchpad.net/~openstack Post to : openstack@lists.launchpad.net Unsubscribe : https://launchpad.net/~openstack More help : https://help.launchpad.net/ListHelp
