[Openstack] Extension Documentation

Anne Gentle anne at openstack.org
Fri Dec 9 14:17:15 UTC 2011


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




More information about the Openstack mailing list