Open Stack

Hi all,
I'm back and mellow after my week at the beach. Here's what's going on in
the world of docs.

We had our doc team meeting this morning. The 2nd and 4th Wed. are Europe
and North America times, the 1st and 3rd Wed. are for Australia and Pacific
area time zones. Find the meeting logs here:
https://wiki.openstack.org/wiki/Documentation/MeetingLogs and all are
welcome.

1. In review and merged recently:

RabbitMQ is now in use everywhere in the install guides, rather than
documenting Qpid just for Fedora/CentOS/RHEL.

The Admin User Guide has been updated for the Icehouse dashboard UI with
https://review.openstack.org/#/c/98484/.

The Configuration Reference now shows new, deprecated, and changed options
release-over-release with this: https://review.openstack.org/#/c/97621/.

There are three install guide patches for Debian that need review:

 https://review.openstack.org/97158

 https://review.openstack.org/96687

 https://review.openstack.org/98329

2. High priority doc work:

I've gone through blueprints. One blueprint that I want to discuss further
is the quality of the Python client docs that are stored with each
project-*client repo. Their doc quality is often low, and Tom filed a
blueprint to try to address. Originally we added the Python SDK chapter to
the User Guide in hopes of alleviating some of this difficulty.
http://docs.openstack.org/user-guide/content/ch_sdk.html

Rather than chase quality across nine (integrated) python-*client repos,
I'd prefer to spend time to document the common openstack client and common
SDKs. However, those are probably six months to a year from widespread use.
So is this blueprint a fix for now while we work on the longer term? I'd
like more input here to plan a way forward.

3. Doc work going on that I know of:

I've approved juno blueprints for:
-Install Guide improvements
-Adding Monitoring to the User Guide (or Admin User Guide as needed)
-Adding a Databases chapter to the User Guide
-Adding release-to-release change info to config reference
-Adding Orchestration template reference guide to the User Guide
-An overarching OpenStack API document is started, Diane has the blueprint.
-I believe the "deployment-template" blueprint will be fulfilled with the
upcoming architecture book sprint.
-The blueprint for "understanding networking" is still in discussion, and I
think we have agreement to start a new Networking Admin Guide. Let me know
if you'd like to run point on that -- Karin and Lana have ideas and can
probably run with it.
- Updating to use the ITS tool for doc translation is in discussion with a
beta available. I'm good with this work as long as the localization team is
interested.
-Training manuals have a blueprint that they'll move to their own Launchpad
location, I believe.
- I'm working on a redesign for the docs site, still drafting solutions.

There are blueprints still lingering:
-Automation of API samples from the nova repo to the api-site repo - do we
still want to do this?
-Redocument Xen -- I think there is interest, would someone like to be
point? John Garbutt or Bob Ball or both?
-VPNaaS Neutron deployment -- Edgar, is this completed with
http://docs.openstack.org/api/openstack-network/2.0/content/vpnaas_ext.html?
-Keystone updates - Joe Heck originally wanted to do this one, and we need
to document more of v3 from deployers and users standpoint. Any interest?

I'll reach out to individuals as well.

4. New incoming doc requests:

We've recorded blueprints for incoming doc requests. Thanks for all the
good ideas.

5. Doc tools updates:

Diane's working on a change to make query parameters show up in the API
reference output. You can test it here:
https://review.openstack.org/#/c/99198/. To test the maven clouddocs plugin
prior to a release, you checkout a local copy of the patch of the plugin,
then run:
mvn clean install

Make a note of what -SNAPSHOT version is built, then change the pom.xml of
what you want to build to the newly, locally built SNAPSHOT version. Run:
mvn -U clean generate-sources

The -U parameter forces your local environment to use the SNAPSHOT version.
Then look at the local output.

Andreas is out this week and next, so I'm hesitant to cut a release of
openstack-doc-tools without him. The change that's still pending is the
new/changed/deprecated options in the configuration reference.

6. Other doc news:
The architecture book sprint starts July 7th and goes all week, with a new
PDF by July 11th. The week following we'll bring it into docbook and our
review process. Thanks to all our hearty authors taking on the challenge!
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-dev/attachments/20140611/ce20e95a/attachment.html>