Open Stack

On Mon, Jul 1, 2013 at 9:08 PM, Tom Fifield <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>> 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



> > 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>>
> >      >>
> >      >>
> >      >>
> >      >>
> >      >> _______________________________________________
> >      >> Openstack-docs mailing list
> >      >> 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>
> >      >
> 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>
> >     http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs
> >
> >
> >
> >
> > --
> > Anne Gentle
> > annegentle at justwriteclick.com <mailto:annegentle at justwriteclick.com>
>
>


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