Open Stack

Awesome news, and awesome work, Anne and all the doc contributors! :)

On Fri, Sep 23, 2011 at 4:36 PM, Anne Gentle <anne at openstack.org> wrote:
> Hi all -
> I wanted to take a breath after the Diablo release to send you a note about
> the state of the docs and the upcoming Design Summit.
>
> Doc Blitz!
> We had over 100 comments on the docs.openstack.org/docblitz pages, way to
> go! In the afternoon session we had a comment a minute. My inbox was
> overflowing. You can read the RSS feed of all the comments at
> http://openstackdocs.disqus.com/latest.rss (or subscribe to that feed for
> ongoing updates). Web stats show that people reviewed over 250 pages of
> content in the single day. We also unveiled the new landing page, thanks to
> Todd Morey. It separates Admin docs from API docs more clearly. We're
> looking for ways to make the page more engaging and add call to action style
> language as well - suggestions welcome!
>
> API Documentation
> You know about this if you've kept up with the list threads, but I'll let
> you know again that each of the OpenStack APIs now have their own git
> repositories:
> openstack/identity-api (Keystone)
> openstack/image-api (Glance)
> openstack/compute-api (Nova)
> openstack/object-api (Swift)
>
> There were these main goals with this move:
> 1) To live where the code lives, or as close to it as possible
> 2) To avoid having DocBook diffs in the code source trees
> 3) To enable reviews with core team members and documentation team members
>
> The Keystone team is testing a new way to integrate WADL within the DocBook,
> which I believe brings the code closer to the doc. They're ironing out the
> wrinkles as they go, but the plan is to release this tool so that other
> OpenStack projects can use it if they'd like. You can see the output in the
> Verb/URI/Description headers such as on this page:
> http://docs.openstack.org/api/openstack-identity-service/2.0/content/Admin_API_Service_Developer_Operations-d1e1356.html.
>
> Admin Documentation Moved to Github
> In addition to all the API guides moving to Github, the Administrator guides
> are now also housed on Github in the
> https://github.com/openstack/openstack-manuals repository. This repo
> includes Compute, Object Storage, Image Service, and Identity Service
> installation, configuration, and administration information. I chose to keep
> these all together since these projects will release on the same schedule. I
> could be convinced to move them apart on a per-book basis, but we'll start
> here for now. There are pom.xml files that can build each book individually,
> and all merges are automatically built to docs.openstack.org/trunk through
> the OpenStack Jenkins server.
>
> New openstack-doc-core Team
> In alignment with the core project teams and in order to enable Gerrit
> reviews, we have a new openstack-doc-core team. It currently consists of me,
> David Cramer, and Kevin Bringard. We three have the ability to +2 in a
> Gerrit review, which causes the merge to occur. I'm excited to have a
> doc-core team to help with reviews of API docs as well as the new
> openstack-manuals repo on Github that houses the administrator guides.
>
> Starter Guide on Launchpad
> The OpenStack Starter Guide from CSS OSS has been hugely helpful for people
> approaching OpenStack, and the web stats for the docs.openstack.org web site
> showed at least five of its pages climbed into the top ten the first month
> it was published on the site. They are working on updates to the guide for
> Diablo in time for an October 13th deadline. Feel free to jump in and help
> them at https://code.launchpad.net/~cssoss/openstackbook/oneiric.
>
> Let's Talk Some Docs at the Design Summit
> I'd like to get together to talk about the current state of the
> documentation at the Design Summit. Here's the session to look for:
> http://summit.openstack.org/sessions/view/26. I hope to see many of you
> there!
>
> Thanks,
> Anne
>
> Anne Gentle
> anne at openstack.org
> my blog | my book | LinkedIn | Delicious | Twitter
> _______________________________________________
> 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
>
>