Open Stack

Anne,

The VPN section looks completed but we are introducing new changes on the services area.
I have been using Neutron team to include DocImpact on their commit messages to keep track of news changes for the Docs. On the last Neutron IRC meeting we have agreed that all commits missing DocImpact will be –1 until they include it.
So, it will help in keeping track on the new features or changes on existing ones.

Cheers,

Edgar

From: Anne Gentle <anne at openstack.org<mailto:anne at openstack.org>>
Date: Wednesday, June 11, 2014 at 10:32 AM
To: "openstack-docs at lists.openstack.org<mailto:openstack-docs at lists.openstack.org>" <openstack-docs at lists.openstack.org<mailto:openstack-docs at lists.openstack.org>>, OpenStack Development Mailing List <openstack-dev at lists.openstack.org<mailto:openstack-dev at lists.openstack.org>>
Cc: Glen Campbell <glen.campbell at rackspace.com<mailto:glen.campbell at rackspace.com>>, Rose Coste <rose.coste at rackspace.com<mailto:rose.coste at rackspace.com>>
Subject: [Openstack-docs] What's Up Doc? June 11 2014

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/ef053570/attachment.html>