Open Stack

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

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 docs or
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>
> >>
> >>
> >>
> >>
> >> _______________________________________________
> >> Openstack-docs mailing list
> >> 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
> > http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs
>
>
> _______________________________________________
> Openstack-docs mailing list
> Openstack-docs at lists.openstack.org
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs
>



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