openstack team mailing list archive

[Jorge Williams <jorge.williams@xxxxxxxxxxxxx>]

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 <heckj@xxxxxxx>
Date: Fri, 9 Dec 2011 11:47:27 -0800
To: Brian Waldon <brian.waldon@xxxxxxxxxxxxx>
Cc: "openstack@xxxxxxxxxxxxxxxxxxx (openstack@xxxxxxxxxxxxxxxxxxx)"
<openstack@xxxxxxxxxxxxxxxxxxx>
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.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/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@xxxxxxxxxxxxxxxxxxx
>>>> Unsubscribe : https://launchpad.net/~openstack
>>>> More help   : https://help.launchpad.net/ListHelp
>>> 
>>> _______________________________________________
>>> Mailing list: https://launchpad.net/~openstack
>>> Post to     : openstack@xxxxxxxxxxxxxxxxxxx
>>> Unsubscribe : https://launchpad.net/~openstack
>>> More help   : https://help.launchpad.net/ListHelp
>> 
>> 
>> _______________________________________________
>> Mailing list: https://launchpad.net/~openstack
>> Post to     : openstack@xxxxxxxxxxxxxxxxxxx
>> Unsubscribe : https://launchpad.net/~openstack
>> More help   : https://help.launchpad.net/ListHelp
>
>
>_______________________________________________
>Mailing list: https://launchpad.net/~openstack
>Post to     : openstack@xxxxxxxxxxxxxxxxxxx
>Unsubscribe : https://launchpad.net/~openstack
>More help   : https://help.launchpad.net/ListHelp