openstack team mailing list archive

[Anne Gentle <anne@xxxxxxxxxxxxx>]

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@xxxxxxxxxxxxx
 my blog <http://justwriteclick.com/> | my
book<http://xmlpress.net/publications/conversation-community/>|
LinkedIn <http://www.linkedin.com/in/annegentle> |
Delicious<http://del.icio.us/annegentle>|
Twitter <http://twitter.com/annegentle>