Open Stack

Hi Anne,
I know I don't have street cred yet, but here's my offering.

*Administration Guide / Admin User Guide*
Am thinking that the biggest problem is one of audience. The restructure 
blueprint says that the 'Administration Guide' is for deployers and not 
for the administrative user. And it says that one of the tasks of a 
deployer is to 'run' the cloud.
This feels like a mixed target, the deployer doesn't necessarily stick 
around to administer what's been deployed. (Is this definition a result 
of the Ops Guide? That too could be divied up now that the suite is 
growing.)

With this definition of deployer, of course the Admin guide would be 
huge, including both deployment and management tasks. And is why the 
Admin Guide blueprint is so large, including information on installation 
and configuration in each project chapter.  If you clearly separate the 
audience, I believe there should be only one Administration guide, for 
the person sitting down to manage the beast after it's been deployed.

IMVHO, the Admin User Guide could be the 4.0 Administration Guide (with 
its clear focus on admin tasks), with the next release including the 
broader admin tasks from Nick's specification (security, 
troubleshooting, etc).

*Project Admin Guides / Single Admin Guide*
If it is at all feasible, I'd keep the project admin guides going. And 
use xi:includes to bring their content into the Administration Guide 
where relevant. There will be inconsistency across project guides, but:
--They are useful for component-focused issues.
--Detailed, advanced material can be introduced which might be out of 
place in an overarching admin guide.
--Dev folk will always be more interested in producing content for their 
own project doc (and then it can be referenced elsewhere).

cheers, Summer

Summer Long
OpenStack Documentation
Engineering Content Services

Red Hat Asia Pacific
Brisbane, Australia
slong at redhat.com <mailto:slong at redhat.com>

On 07/11/2013 05:21 AM, Anne Gentle wrote:
>
> 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)?
>
Nick: Yes. I know that was the goal of the Ops Guide, but I think it 
landed in a different, and just as vital, spot. I think a comprehensive 
guide makes it possible for someone to avoid getting lost in a sea of 
books, as the guide will, well, guide them through.
>
> Should we create an Admin User Guide with Diane's outline [5]?
>
Nick: Absolutely. What she has planned is a vital look at the essentials.
>
>
> Does an Admin User Guide eliminate the need for a separate OpenStack 
> Administration Guide?
>
Nick: No. I see it as a progression. start with Diane's book, then 
pickup the guide for more in depth understanding of concepts.
>
>
> Should we keep the separate Admin Guides per project? (That brings 
> along the problem with owners and inconsistency.)
>
Nick:Yes.the reality is that those owners are sometimes the best at 
this, sometimes not. A guide like this lets us improve where necessary 
without ditching the good stuff.    Remember we are not talking about 
getting rid of the great work you have done (and are doing) . Just the 
opposite.
>
>
> 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)
>
>
>
> _______________________________________________
> Openstack-docs mailing list
> Openstack-docs at lists.openstack.org
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20130711/7f2146fc/attachment.html>