Open Stack

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.

:)


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