[Openstack-docs] Administration Guide-Design
Anne Gentle
anne at openstack.org
Tue Jul 2 02:25:58 UTC 2013
On Mon, Jul 1, 2013 at 9:22 PM, Tom Fifield <tom at openstack.org> wrote:
> 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'.
>
I like!
I think it's spot on with Diane's conclusions too. Just have to start
yankin'.
>
> > > 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>
>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20130701/fa6a3bd1/attachment-0001.html>
More information about the Openstack-docs
mailing list