Open Stack

On Wed, Dec 11, 2013 at 5:31 PM, Anne Gentle <anne at openstack.org> wrote:

> 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:
>
I left out an important update for doc tools -- Sphinx 1.2 was just
released and it is incompatible with distutils in python 2.7. This means
that all projects need to fix their doc builds either by subscribing to
openstack/requirements which already has the correct version of Sphinx
pinned, or by pinning sphinx>=1.1.2,<1.2 in your own requirements file. See
the thread on openstack-dev at
http://lists.openstack.org/pipermail/openstack-dev/2013-December/021863.htmlor
ask a friendly infrastructure dev for help.
Anne


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