On Wed, Dec 11, 2013 at 5:31 PM, Anne Gentle <[email protected]> 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! >
_______________________________________________ OpenStack-dev mailing list [email protected] http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
