Open Stack

Hi all,


I'd like to get feedback about the *administration* portion of our
documentation refactoring plan [1], which we overlooked when we created the
original documentation restructuring blueprint.[4]


tl;dr - We need to make a decision about guides for
administrators/operators going forward. Please review the following
detailed analysis.


Tom, Diane, Nick, Nermina, I, and others have been reviewing the following
blueprints for the Havana release:



   - [1] restructure documentation blueprint. Describes a plan to
   restructure the OpenStack documentation. However it did not address Admin
   Guides.
   - [2] modularize admin guide. Recommends a comprehensive administrative
   guide, with the option of producing smaller project-specific guides.
   - [3] os-admin-docs. Outlines a comprehensive administration guide that
   describes everything that an administrator/operator needs to install,
   deploy, and maintain an OpenStack cluster.

I have a few concerns about these blueprints, which is why I'd like *more
eyes please*! To see if we're talking crazy talk. :)


My concerns:

   - We already have smaller admin guides, which are maintained by project
   teams. The block storage and networking teams are quite active in
   maintaining their admin guides. However, the object storage and compute
   teams are not as invested in their admin guides. So there are issues with
   having smaller, project-directed guides – lack of consistency, content
   mismatch, and other issues.
   - The comprehensive administrative guide seems to have the same goals as
   the existing Operations Guide. In that book sprint, the stated goal was to
   create a book for new OpenStack cloud operators.
   - We already hear that the Compute Admin Guide is too long. How can a
   longer guide really be the answer? Lorin pulled out the Image Management
   chapter to make the OpenStack Virtual Machine Image Guide, and the
   config chapter is moving to the new Configuration Reference. We've been
   gutting the Compute Admin Guide since the Summit to try to slim it into
   just a Config Ref and an Admin User Guide. So we're hoping that the gutting
   will result in a set of books, which then coupled with the Operations
   Guide, is the fresh-minted OpenStack administrator's ticket to success.
   - The plan for a comprehensive administration guide might not fit with
   our plans for content modularity and doc ownership.

The end goal of the admin doc restructuring is to make the Operations
Guide, the Admin Guides, and the Config Reference all work well together.
We want to avoid redundancy and we want to provide a clear path through the
documentation. And we must scope this work correctly for the upcoming
October release date.


*Questions:*


Do we need a large, comprehensive Admin guide (now that I see the outline
I'm a little daunted)?


Should we create an Admin User Guide with Diane's outline [5]?


Does an Admin User Guide eliminate the need for a separate OpenStack
Administration Guide?


Should we keep the separate Admin Guides per project? (That brings along
the problem with owners and inconsistency.)


Or maybe there is another option or two or eight that we haven't thought of?


Thanks for reading this far! We need more opinions and then a decision for
the path forward.

Thanks,

Anne



1
https://blueprints.launchpad.net/openstack-manuals/+spec/restructure-documentation

2
https://blueprints.launchpad.net/openstack-manuals/+spec/modularize-admin-guide

3 https://blueprints.launchpad.net/openstack-manuals/+spec/os-admin-docs

4
https://wiki.openstack.org/w/index.php?title=Blueprint-restructure-documentation&diff=25490&oldid=24528

5
https://wiki.openstack.org/wiki/Blueprint-restructure-documentation#OpenStack_Admin_User_Guide


More reference information.


These are the current titles for the admin audience:

OpenStack Block Storage Service Administration Guide

OpenStack Compute Administration Guide

OpenStack Network Service Administration Guide

OpenStack Object Storage Administration Guide

OpenStack Operations Guide

OpenStack High Availability Guide

OpenStack Virtual Machine Image Guide

OpenStack Security Guide


These are the additional titles for Havana under consideration:

Admin User Guide (sourced from End User Guide)

OpenStack Administration Guide (sourced by combining from modular content)
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20130710/3e82b9fe/attachment-0001.html>