Open Stack

On 02/07/13 12:20, Anne Gentle wrote:
> 
> 
> 
> On Mon, Jul 1, 2013 at 9:08 PM, Tom Fifield <tom at openstack.org 
> <mailto:tom at openstack.org>> wrote:
> 
>     On 02/07/13 12:05, Anne Gentle wrote:
>      >
>      >
>      >
>      > On Mon, Jul 1, 2013 at 7:59 PM, Tom Fifield <tom at openstack.org
>     <mailto:tom at openstack.org>
>      > <mailto:tom at openstack.org <mailto:tom at openstack.org>>> wrote:
>      >
>      >     Welcome Summer! It's great to have you.
>      >
>      >     So, up until 30 seconds ago when I checked the wiki, I
>     thought I had a
>      >     good idea of our restructure, which is laid out as:
>      > https://wiki.openstack.org/wiki/Blueprint-restructure-documentation
>      >
>      >     On of the points of the restructure was to do away with the
>     current
>      >     administration guide (eg
>      > http://docs.openstack.org/trunk/openstack-compute/admin), because
>      >     operators found it "exhaustive to the point of being past
>     useless"[1].
>      >
>      >     The aim that I remember was to create a Configuration
>     Reference, which
>      >     would have much shorter introductions to each of the features in
>      >     OpenStack, followed by a table of their configuration options
>      >     automatically generated from code.
>      >
>      >     This was to be accompanied by a User guide, one for end-users
>     of the
>      >     cloud, and one for Administrators of the cloud (wich much shared
>      >     content).
>      >
>      >     However, I now see that "Administration Guide" has been added
>     to the
>      >     wiki, which has caused me great confusion :)
>      >
>      >
>      > A couple of reasons for this addition back.
>      > - After Diane's analysis of the user guide, she found there are
>     plenty
>      > of "admin user" tasks that need a guide. The exact title of this new
>      > guide we weren't sure of though.
>      > - After analysis of the Block Storage Administration Guide and the
>      > Networking Administration Guide, both of which have quite a few
>      > "owners," I'm am not yet convinced we can get rid of a book with the
>      > title Administration Guide. Nick, Diane, and I talked about this last
>      > week and Nick was working on an outline.
>      > - The specific feedback you mention "being past useless" is
>     specific to
>      > the Compute Administration Guide. I don't think we can throw out all
>      > Administration Guides due to input on the Compute Administration
>     Guide.
>      > - We agreed at the Summit that more detailed analysis was
>     required. This
>      > is what we're doing now.
>      >
>      > Hope that clears up any confusion.
> 
>     That all makes sense, but then I question why we need an
> 
>     "Administration Guide"
> 
>     and a
> 
>     "Admin User Guide"
> 
>     If these two get merged, that'd solve my current issue.
> 
>     :)
> 
> 
> 
> Yeah the idea started when Diane looked at the (excellent) SUSE Admin 
> User Guide, and she's still doing a detailed analysis, except that the 
> Identity API v3 took front-and-center priority... so it'll be at least 
> another week or two before we have a good answer. I'd like Nick to make 
> a judgement call there also after he noodles on it a while.
> 
> My guess/hunch is that we don't need an Admin User Guide separate from 
> an Administration Guide... that it's a title change that's not needed. 
> Then I think, it sure would be nice to reuse some distro content with 
> little rework or by adding collaborators. Then I think, someone needs to 
> really read through the content to make that call. So you can tell I'm 
> wanting more analysis. I'm hopeful Diane and Nick will read and conclude 
> with "one Admin Guide to rule them all" heh heh heh.
> Anne

My analysis is in
https://review.openstack.org/#/c/35027/5/doc/src/docbkx/openstack-config/ch_computeconfigure.xml

Look for the lines starting with 'status'.

>      > Nick specifically is doing an analysis of admin guides.  Summer
>     can you
>      > and Nick work together on a detailed outline and analysis? One
>     question
>      > he is working through is whether "OpenStack Administration" is
>     important
>      > or "Block Storage Administration" is important, as well as "Is
>      > Administration daily tasks and troubleshooting? More or less?"
>      >
>      > My current thinking is:
>      > Administration Guides per project may have a place. John Griffith and
>      > Dan Wendlandt did a great job gathering content around their
>     projects,
>      > Block Storage and Networking respectively. This is my line of
>      > questioning in the survey I sent out recently. [2] Specifically,
>     these
>      > two questions:
>      > 4. As a reader, would you prioritize project docs over overarching
>      > docsor vice-versa? Why?
>      >
>      >
>      > 5. As a project maintainer, which docs would you value more highly,
>      >     combined solutions docs or docs specific and detailed for
>     your project? Why?
>      >
>      > I know we have a lot more to work through to get to the right
>     library of
>      > books for OpenStack, as well as working on a definition of "official"
>      > and a scope for what is released for a release. All of these
>     questions
>      > are tangled together and we'll all work together to straighten
>     them out.
>      > Tom and I spoke last week about a new layout for the landing page so
>      > that we can set expectations early and provide focused efforts.
>     That's
>      > why I'm very glad you're asking early, Summer, and that we're all
>     able
>      > to input our findings as we go.
>      >
>      > Hopefully I'm detangling and not entangling! Let's talk more
>     about it at
>      > next week's meeting and on this list.
>      > Anne
>      >
>      > [2]
>      >
>     http://lists.openstack.org/pipermail/openstack-docs/2013-June/002037.html
>      >
>      >
>      >
>      >     Regards,
>      >
>      >
>      >     Tom
>      >
>      >     [1]https://bugs.launchpad.net/openstack-manuals/+bug/1110137
>      >
>      >     On 02/07/13 10:45, Nicholas Chase wrote:
>      >      >
>      >      > On 7/1/2013 8:06 PM, Summer Long wrote:
>      >      >> Hi Anne,
>      >      >> I've been working on OpenStack docs over at Red Hat, and
>     would
>      >     like to
>      >      >> help with the OS Admin Guide.
>      >      >> Can you tell me where I can contribute to its design? Steve
>      >     Gordon tells
>      >      >> me that the intent is to consolidate the various
>     component guides?
>      >      >
>      >      > Hi, Summer --
>      >      >
>      >      > I've actually been pretty quiet here, but I'm currently
>     working on a
>      >      > plan for this consolidation -- blueprint to be up shortly, I
>      >     promise! --
>      >      > would you like to get together sometime this week to chat
>     about
>      >     how we
>      >      > might work together on this?
>      >      >
>      >      >> I'm new to working with Open Source docs (previously
>     worked with
>      >      >> proprietary software houses), so am pretty excited about
>      >     stepping over
>      >      >> to the light side!
>      >      >
>      >      > I can't speak for anyone else, but for me, nice to have
>     you here. :)
>      >      >
>      >      > ----  Nick
>      >      >
>      >      >> thanks,
>      >      >> Summer
>      >      >>
>      >      >>
>      >      >> Summer Long
>      >      >> OpenStack Documentation
>      >      >> Engineering Content Services
>      >      >>
>      >      >> Red Hat Asia Pacific
>      >      >> Brisbane, Australia
>      >      >> slong at redhat.com <mailto:slong at redhat.com>
>     <mailto:slong at redhat.com <mailto:slong at redhat.com>>
>      >     <mailto:slong at redhat.com <mailto:slong at redhat.com>
>     <mailto:slong at redhat.com <mailto:slong at redhat.com>>>
>      >      >>
>      >      >>
>      >      >>
>      >      >>
>      >      >> _______________________________________________
>      >      >> Openstack-docs mailing list
>      >      >> Openstack-docs at lists.openstack.org
>     <mailto:Openstack-docs at lists.openstack.org>
>      >     <mailto:Openstack-docs at lists.openstack.org
>     <mailto:Openstack-docs at lists.openstack.org>>
>      >      >>
>     http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs
>      >      >>
>      >      >
>      >      > _______________________________________________
>      >      > Openstack-docs mailing list
>      >      > Openstack-docs at lists.openstack.org
>     <mailto:Openstack-docs at lists.openstack.org>
>      >     <mailto:Openstack-docs at lists.openstack.org
>     <mailto:Openstack-docs at lists.openstack.org>>
>      >      >
>     http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs
>      >
>      >
>      >     _______________________________________________
>      >     Openstack-docs mailing list
>      > Openstack-docs at lists.openstack.org
>     <mailto:Openstack-docs at lists.openstack.org>
>      >     <mailto:Openstack-docs at lists.openstack.org
>     <mailto:Openstack-docs at lists.openstack.org>>
>      > http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs
>      >
>      >
>      >
>      >
>      > --
>      > Anne Gentle
>      > annegentle at justwriteclick.com
>     <mailto:annegentle at justwriteclick.com>
>     <mailto:annegentle at justwriteclick.com
>     <mailto:annegentle at justwriteclick.com>>
> 
> 
> 
> 
> -- 
> Anne Gentle
> annegentle at justwriteclick.com <mailto:annegentle at justwriteclick.com>