Open Stack

Here are six things you want to know from OpenStack doc-land.

I've cross posted to openstack-docs and openstack-dev, so please reply only
to the openstack-docs list with any questions or feedback.

We had our team meeting this week, and you can read the log and minutes at
https://wiki.openstack.org/wiki/Documentation/MeetingLogs#2013-08-13.

1. In review and merged this past week:

We've had nearly 100 patches merged in the last two weeks including some
changes to the way the validation script works. I know this caused some
churn and consternation, sorry about that. But I do believe the tidying of
the markup will make the docs more consistent and easier to walk up to and
change.

Cleanup is all good but we do want more doc bug fixing. Many bugs were
fixed (like over 20) with the autodoc work. However there are many bugs
from DocImpact. Which leads me to the high priority doc work.

2. High priority doc work:

https://launchpad.net/openstack-manuals/+milestone/havana is the list of
doc bugs and blueprints we're focusing on for the Havana release. Feature
freeze is Sept 5th for all the projects. We need to have the repos ready
for bug fixing.

I've directed Shaun McCance, contractor at Cisco, to get a draft for the
Install Guide going. The draft architectures are here:
https://etherpad.openstack.org/havanainstall.

I am meeting with the teams at their weekly meetings or PTLs individually
to determine what happens to the Administration Guides. Our initial
analysis shows that much content moves to the Configuration Reference and
Admin User Guide. I'll talk to each team about the net changes there.

3. Doc work going on that I know of:

Diane Fleming is working on a new Admin User Guide currently.

The review queue has lots of markup changes, refer to
http://wiki.openstack.org/Documentation/Conventions to see what markup is
correct.

The Compute v3 API documentation is being sourced by IBM and the docs team
is ready to help as needed.

4. New incoming doc requests:

I talked with representatives from the Heat team last week about a Template
guide, and it looks like someone wrote it - - great!

5. Doc tools updates:
The Maven plugin that builds our docs is sourced at
https://github.com/rackerlabs/clouddocs-maven-plugin and just released
version 1.9.0.

Our pom.xml files still point to 1.8.0 but we could start testing 1.9.0
which adds supports for olinks. By using olinks instead of our current
linking with xrefs would prevent Oxygen from showing non-valid file
warnings in individual chapter files and adds an easier interface for
finding cross-reference links. David Cramer can demo at the Boot Camp, and
then we'll need to make decisions about how much cross-referencing we want.
With fewer books going to a "released" docs site, we may want to limit the
use of cross-references altogether, but let's discuss in person. Our
current linking conventions are here:
https://wiki.openstack.org/wiki/Documentation/Conventions#Linking.

Another addition for 1.9.0 is adding parameter style and type to the
http://api.openstack.org/api_ref.html page. Review for testing at
https://review.openstack.org/42011.

6. Other doc news:

Docs Boot Camp is less than a month away and Tom, Nick, Shaun and I are
working on the details. We should have over 20 attendees, and more than
half are quite new to docs. Looking forward to it!

Nick Chase at Mirantis is finalizing a "how to contribute" guide for docs
and hopefully we can go over it at the Doc Boot Camp.

Any other exciting doc news to share? Let us know at
openstack-docs at lists.openstack.org.

Thanks,

Anne
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-dev/attachments/20130814/69a63340/attachment.html>