Open Stack

Great points, Summer! - Nermina

On Thursday, July 11, 2013, Summer Long wrote:

>  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 <javascript:_e({}, 'cvml', '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.
>
>  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 listOpenstack-docs at lists.openstack.org <javascript:_e({}, 'cvml', '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/a4835f76/attachment-0001.html>