Inline: -----Original Message----- From: Anne Gentle <a...@openstack.org> Date: Fri, 9 Dec 2011 08:17:15 -0600 To: Jorge Williams <jorge.willi...@rackspace.com> Cc: "openstack@lists.launchpad.net (openstack@lists.launchpad.net)" <openstack@lists.launchpad.net> Subject: Re: [Openstack] Extension Documentation
>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. Right. That's the intent. >2. In the header, I don't believe "Extensions Documentation" is the >correct label, probably just highlight "Documentation". Okay, done. >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. Can we start off by putting a link on "Related Resources" section on the http://docs.openstack.org/api/ site? >4. All of the links need to add an additional /content/ to the link to >avoid redirects. Okay, done. >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. Okay, done for the compute extension, I'll get working on the Keystone ones. >6. I made some minor changes to the DocBook template so that people >can find the WADL normalizer tool. Thanks! >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. If you're building a reference site, I suppose it makes sense to include extension info as well as long as there's clear indication that it's an extension. >8. We need a discussion about who will review these extension >submissions and ensure they get built. So, for OpenStack extensions, then the PTL of the project should approve and really as Waldon said the nova-api team in compute for example. Vendor extensions should be reviewed by individual vendors. > >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? For sure, I'd love to have feedback on the templates myself :-) https://github.com/RackerWilliams/extension-doc-templates > >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/Overvie >>w.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
