[Openstack-docs] Administration Guide-Design
Tom Fifield
tom at openstack.org
Tue Jul 2 02:28:20 UTC 2013
On 02/07/13 12:25, Anne Gentle wrote:
>
>
>
> On Mon, Jul 1, 2013 at 9:22 PM, Tom Fifield <tom at openstack.org
> <mailto: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>
> > <mailto: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>>
> > > <mailto: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'.
Yay :)
See also, in that same patch what I did to the VNC stuff, separating out
the "using-vnc-console" from the "configuring vnc console".
Worthy of +2 love ? :D
>
> > > 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>>>
> > > <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 <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>>
> > > <mailto: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>>
> > > <mailto: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>>
> > > <mailto: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>>
> > <mailto: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>
> <mailto:annegentle at justwriteclick.com
> <mailto:annegentle at justwriteclick.com>>
>
>
More information about the Openstack-docs
mailing list