Open Stack

Thanks to new doc patchers Shilla Saebi and Thomas Herve for their clean up
work, especially for the Identity API docs and Heat install!

Be ready for 12/20/13 Doc Bug Day! Looking forward to it.

1. In review and merged this past week:

The Install Guide is still the most worked-on document. I'd like to shift
from that now that we're past milestone-1 and work harder on the Cloud
Administrator Guide and Operations Guide, to separate out items from the
Configuration Reference that are "how to" and move them to the Cloud
Administrator Guide. Nermina made progress on the Cloud Administrator Guide
additions from the Configuration Reference, her analysis is here:
http://lists.openstack.org/pipermail/openstack-docs/2013-December/003459.html

Lana Brindley was in Texas this week, and she's going to take on
maintenance of the User Guide and Admin User Guide with some additions of
scripts that are common user/admin user tasks with CLIs. She's also looking
into our processes and reviews and making good strides towards bringing in
developer teams for reviews after they use the DocImpact flag. Thanks Lana!

2. High priority doc work:

To me, one high priority is to get the config options done for milestone 1
release.

Another priority is for me to write a "content spec" for each book that we
currently maintain, so that incoming projects can easily "plug in" to each
deliverable. If I had to write a short description of each book, it'd be:

Installation Guide - Describes a manual install process for multiple
distributions including CentOS, Debian, Fedora, OpenSUSE, RedHat Enterprise
Linux, SUSE Enterprise Linux, and Ubuntu.

Configuration Reference - Contains a reference listing of all configuration
options for core and integrated OpenStack services.

Cloud Administrator Guide - Contains how-to information for managing an
OpenStack cloud as needed for your use cases, described in this document.

High Availability Guide - Describes potential strategies for making your
OpenStack services and related controllers and data stores highly available.

Operations Guide - Offers information for designing and operating OpenStack
private or public clouds plus best practices for day-to-day operations.

Security Guide - Provide best practices and conceptual information about
securing an OpenStack cloud

Virtual Machine Image Guide - Shows you how to obtain, create, and modify
virtual machine images that are compatible with OpenStack.
End User Guide - Shows OpenStack end users how to create and manage
resources in an OpenStack cloud with the OpenStack dashboard and OpenStack
client commands.

Admin User Guide - Shows OpenStack admin users how to create and manage
resources in an OpenStack cloud with the OpenStack dashboard and OpenStack
client commands.

API Quick Start - A brief overview of how to send requests to endpoints for
OpenStack services.

I'd like for projects to understand what goes where and be able to write
sections that fit into these titles. I'm not recommending that you create
your own title, but understand where your section can go in the wider
picture of OpenStack docs.

3. Doc work going on that I know of:

See below for the developmental edit of the O'Reilly edition of the
Operations Guide.

Shaun's working on the autodoc for configuration option tables for the
icehouse-1 milestone.

4. New incoming doc requests:

The Triple-O team would like to talk about how to plug into the OpenStack
existing docs. Feel free to reach out on details, while we are going to
stick with the manual install for this release (Icehouse), perhaps the
Triple-O team can get a head start. Open to ideas after hearing from them
in the weekly project meeting.

5. Doc tools updates:

The infra team is working on ways to version and deploy the
clouddocs-maven-plugin (wow, that's verbing a noun).

6. Other doc news:

The development edit for the Operations Guide from O'Reilly has begun, and
by tomorrow we should have input on a few more chapters. Here are some
overarching comments from Brian Anderson you may like to help us dig into:

---

- an expanded Preface which situates the Operations Guide in relation to
other, related guides (like the Admin guide you mentioned). A taxonomy of
user roles would be helpful here.
- an introductory chapter about OpenStack, showing, in particular, a
high-level view of an OpenStack deployment and the different sorts of
components. There should be an emphasis on how the components work
together. Some institution-level suggestions would perhaps be helpful here
(what your organization should bear in mind when using OpenStack)
- a sneak peek of Icehouse (in the preface? or as an appendix?)
- more content focusing on how to upgrade from one version to another
(maybe this would be a new chapter?)

As I mentioned, the book is quite "clean". However, we can aim it at our
audience a bit more. As it stands, the book contains a lot of tactics but
not a lot of strategy. What are some broad considerations that our audience
should bear in mind when operating OpenStack?

---

Contact me if you have an interest in a specific area for the Ops Guide.

Also, we welcome the OPW interns who will be working on docs - Miranda
Zhang will be working with Diane Fleming, and Cindy Pallares will be
working on Marconi docs with Flavio Percoco. Welcome new interns!
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-dev/attachments/20131211/3c406cb7/attachment.html>