openstack team mailing list archive

[Jorge Williams <jorge.williams@xxxxxxxxxxxxx>]

Inline:

-----Original Message-----
From: Anne Gentle <anne@xxxxxxxxxxxxx>
Date: Fri, 9 Dec 2011 08:17:15 -0600
To: Jorge Williams <jorge.williams@xxxxxxxxxxxxx>
Cc: "openstack@xxxxxxxxxxxxxxxxxxx (openstack@xxxxxxxxxxxxxxxxxxx)"
<openstack@xxxxxxxxxxxxxxxxxxx>
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.williams@xxxxxxxxxxxxx> 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@xxxxxxxxxxxxxxxxxxx
>> Unsubscribe : https://launchpad.net/~openstack
>> More help   : https://help.launchpad.net/ListHelp