Open Stack

Hi all,
Sorry it took me so long to circle back to this thread, but I think
Summer's analysis is right but I have some nuanced responses.

I've also asked Nermina to finalize her research next week, so stay tuned.

More below.


On Wed, Jul 10, 2013 at 11:23 PM, Summer Long <slong at redhat.com> wrote:

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

Hee. I love street cred. You're gaining it all the time.


>
> *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.)
>
>
When we talked about audience day one of the sprint, 2-3 of the guys in
there wanted a book they could hand over to their newest hires and ask them
to learn enough about OpenStack to help out. There's a "Lay of the Land"
page dedicated to telling people how to learn about their own cloud.
http://docs.openstack.org/trunk/openstack-ops/content/lay_of_the_land.html

Knowing Tom wrote the original restructure blueprint, I've gotta ask, Tom,
who's the deployer? Same as the administrator?

Also we decided day one to split the guide into Architecture decisions and
Day to day administration. I have an emailed/tweeted request to do a Design
Guide next, which would be architecture decisions. Based on the people who
worked on the Ops Guide, the deployer usually does run the cloud, but I do
want that confirmed by Nirmina's research, and by asking Tom to chime in.


> 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.
>

Agreed. I think this was the original intent of the Ops Guide. Another
tidbit about the Ops Guide that might shape our body of work is that the
Foundation is going to hire O'Reilly to do a custom edit the guide, and
there will be an O'Reilly edition of the Ops Guide. We still can do
anything we want to it, it is our content, so the difference between the
O'Reilly edition and our edition may be academic only. But I'm very curious
to hear what pro-level editors at O'Reilly have to say about the contents
and audience of the Ops Guide. Stay tuned this fall.


>
> 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).
>

I think the main concern I have with Nick's outline and specification is
the inclusion of install/deploy. As we've seen from the install thread,
most people are using distros.


>
> *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).
>
>
Yep, agreed on all fronts.

I had a conversation this week with a Swift developer (hi Chuck!) about
separating Admin info out of their dev docs and trying to identify more
info that can go into the Object Storage Admin guide. He's certainly up for
updating and cleaning up but we'd love to identify someone who would just
love to dig into that. One area we identified is that the Swift devs aren't
using DocImpact as effectively as we'd like. For example, an Apache proxy
server implementation is now available but not documented in
openstack-manuals, only in the swift repo. So yes, project teams want to
work on project doc and get support for admin docs.

One missing Admin Guide today is an Identity Admin Guide. It might really
be time for this as the administration tasks for keystone continue to add
up. Currently it's in /common/ and embedded in the Compute Admin Guide.
This is another area that it would be nice to find a doc liaison for the
project team.


> cheers, Summer
>
>  Summer Long
> OpenStack Documentation
> Engineering Content Services
>
> Red Hat Asia Pacific
> Brisbane, Australia
> 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 listOpenstack-docs at lists.openstack.orghttp://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs
>
>
>


-- 
Anne Gentle
annegentle at justwriteclick.com
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20130719/5360f2fc/attachment-0001.html>