<div dir="ltr"><br><div class="gmail_extra"><br><br><div class="gmail_quote">On Mon, Jul 1, 2013 at 9:22 PM, Tom Fifield <span dir="ltr"><<a href="mailto:tom@openstack.org" target="_blank">tom@openstack.org</a>></span> wrote:<br>
<blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex"><div class="im">On 02/07/13 12:20, Anne Gentle wrote:<br>
><br>
><br>
><br>
> On Mon, Jul 1, 2013 at 9:08 PM, Tom Fifield <<a href="mailto:tom@openstack.org">tom@openstack.org</a><br>
</div><div class="im">> <mailto:<a href="mailto:tom@openstack.org">tom@openstack.org</a>>> wrote:<br>
><br>
> On 02/07/13 12:05, Anne Gentle wrote:<br>
> ><br>
> ><br>
> ><br>
> > On Mon, Jul 1, 2013 at 7:59 PM, Tom Fifield <<a href="mailto:tom@openstack.org">tom@openstack.org</a><br>
> <mailto:<a href="mailto:tom@openstack.org">tom@openstack.org</a>><br>
</div><div><div class="h5">> > <mailto:<a href="mailto:tom@openstack.org">tom@openstack.org</a> <mailto:<a href="mailto:tom@openstack.org">tom@openstack.org</a>>>> wrote:<br>
> ><br>
> > Welcome Summer! It's great to have you.<br>
> ><br>
> > So, up until 30 seconds ago when I checked the wiki, I<br>
> thought I had a<br>
> > good idea of our restructure, which is laid out as:<br>
> > <a href="https://wiki.openstack.org/wiki/Blueprint-restructure-documentation" target="_blank">https://wiki.openstack.org/wiki/Blueprint-restructure-documentation</a><br>
> ><br>
> > On of the points of the restructure was to do away with the<br>
> current<br>
> > administration guide (eg<br>
> > <a href="http://docs.openstack.org/trunk/openstack-compute/admin" target="_blank">http://docs.openstack.org/trunk/openstack-compute/admin</a>), because<br>
> > operators found it "exhaustive to the point of being past<br>
> useless"[1].<br>
> ><br>
> > The aim that I remember was to create a Configuration<br>
> Reference, which<br>
> > would have much shorter introductions to each of the features in<br>
> > OpenStack, followed by a table of their configuration options<br>
> > automatically generated from code.<br>
> ><br>
> > This was to be accompanied by a User guide, one for end-users<br>
> of the<br>
> > cloud, and one for Administrators of the cloud (wich much shared<br>
> > content).<br>
> ><br>
> > However, I now see that "Administration Guide" has been added<br>
> to the<br>
> > wiki, which has caused me great confusion :)<br>
> ><br>
> ><br>
> > A couple of reasons for this addition back.<br>
> > - After Diane's analysis of the user guide, she found there are<br>
> plenty<br>
> > of "admin user" tasks that need a guide. The exact title of this new<br>
> > guide we weren't sure of though.<br>
> > - After analysis of the Block Storage Administration Guide and the<br>
> > Networking Administration Guide, both of which have quite a few<br>
> > "owners," I'm am not yet convinced we can get rid of a book with the<br>
> > title Administration Guide. Nick, Diane, and I talked about this last<br>
> > week and Nick was working on an outline.<br>
> > - The specific feedback you mention "being past useless" is<br>
> specific to<br>
> > the Compute Administration Guide. I don't think we can throw out all<br>
> > Administration Guides due to input on the Compute Administration<br>
> Guide.<br>
> > - We agreed at the Summit that more detailed analysis was<br>
> required. This<br>
> > is what we're doing now.<br>
> ><br>
> > Hope that clears up any confusion.<br>
><br>
> That all makes sense, but then I question why we need an<br>
><br>
> "Administration Guide"<br>
><br>
> and a<br>
><br>
> "Admin User Guide"<br>
><br>
> If these two get merged, that'd solve my current issue.<br>
><br>
> :)<br>
><br>
><br>
><br>
> Yeah the idea started when Diane looked at the (excellent) SUSE Admin<br>
> User Guide, and she's still doing a detailed analysis, except that the<br>
> Identity API v3 took front-and-center priority... so it'll be at least<br>
> another week or two before we have a good answer. I'd like Nick to make<br>
> a judgement call there also after he noodles on it a while.<br>
><br>
> My guess/hunch is that we don't need an Admin User Guide separate from<br>
> an Administration Guide... that it's a title change that's not needed.<br>
> Then I think, it sure would be nice to reuse some distro content with<br>
> little rework or by adding collaborators. Then I think, someone needs to<br>
> really read through the content to make that call. So you can tell I'm<br>
> wanting more analysis. I'm hopeful Diane and Nick will read and conclude<br>
> with "one Admin Guide to rule them all" heh heh heh.<br>
> Anne<br>
<br>
</div></div>My analysis is in<br>
<a href="https://review.openstack.org/#/c/35027/5/doc/src/docbkx/openstack-config/ch_computeconfigure.xml" target="_blank">https://review.openstack.org/#/c/35027/5/doc/src/docbkx/openstack-config/ch_computeconfigure.xml</a><br>
<br>
Look for the lines starting with 'status'.<br></blockquote><div><br></div><div style>I like! </div><div style><br></div><div style>I think it's spot on with Diane's conclusions too. Just have to start yankin'.</div>
<div style> </div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">
<div><div class="h5"><br>
> > Nick specifically is doing an analysis of admin guides. Summer<br>
> can you<br>
> > and Nick work together on a detailed outline and analysis? One<br>
> question<br>
> > he is working through is whether "OpenStack Administration" is<br>
> important<br>
> > or "Block Storage Administration" is important, as well as "Is<br>
> > Administration daily tasks and troubleshooting? More or less?"<br>
> ><br>
> > My current thinking is:<br>
> > Administration Guides per project may have a place. John Griffith and<br>
> > Dan Wendlandt did a great job gathering content around their<br>
> projects,<br>
> > Block Storage and Networking respectively. This is my line of<br>
> > questioning in the survey I sent out recently. [2] Specifically,<br>
> these<br>
> > two questions:<br>
> > 4. As a reader, would you prioritize project docs over overarching<br>
> > docsor vice-versa? Why?<br>
> ><br>
> ><br>
> > 5. As a project maintainer, which docs would you value more highly,<br>
> > combined solutions docs or docs specific and detailed for<br>
> your project? Why?<br>
> ><br>
> > I know we have a lot more to work through to get to the right<br>
> library of<br>
> > books for OpenStack, as well as working on a definition of "official"<br>
> > and a scope for what is released for a release. All of these<br>
> questions<br>
> > are tangled together and we'll all work together to straighten<br>
> them out.<br>
> > Tom and I spoke last week about a new layout for the landing page so<br>
> > that we can set expectations early and provide focused efforts.<br>
> That's<br>
> > why I'm very glad you're asking early, Summer, and that we're all<br>
> able<br>
> > to input our findings as we go.<br>
> ><br>
> > Hopefully I'm detangling and not entangling! Let's talk more<br>
> about it at<br>
> > next week's meeting and on this list.<br>
> > Anne<br>
> ><br>
> > [2]<br>
> ><br>
> <a href="http://lists.openstack.org/pipermail/openstack-docs/2013-June/002037.html" target="_blank">http://lists.openstack.org/pipermail/openstack-docs/2013-June/002037.html</a><br>
> ><br>
> ><br>
> ><br>
> > Regards,<br>
> ><br>
> ><br>
> > Tom<br>
> ><br>
> > [1]<a href="https://bugs.launchpad.net/openstack-manuals/+bug/1110137" target="_blank">https://bugs.launchpad.net/openstack-manuals/+bug/1110137</a><br>
> ><br>
> > On 02/07/13 10:45, Nicholas Chase wrote:<br>
> > ><br>
> > > On 7/1/2013 8:06 PM, Summer Long wrote:<br>
> > >> Hi Anne,<br>
> > >> I've been working on OpenStack docs over at Red Hat, and<br>
> would<br>
> > like to<br>
> > >> help with the OS Admin Guide.<br>
> > >> Can you tell me where I can contribute to its design? Steve<br>
> > Gordon tells<br>
> > >> me that the intent is to consolidate the various<br>
> component guides?<br>
> > ><br>
> > > Hi, Summer --<br>
> > ><br>
> > > I've actually been pretty quiet here, but I'm currently<br>
> working on a<br>
> > > plan for this consolidation -- blueprint to be up shortly, I<br>
> > promise! --<br>
> > > would you like to get together sometime this week to chat<br>
> about<br>
> > how we<br>
> > > might work together on this?<br>
> > ><br>
> > >> I'm new to working with Open Source docs (previously<br>
> worked with<br>
> > >> proprietary software houses), so am pretty excited about<br>
> > stepping over<br>
> > >> to the light side!<br>
> > ><br>
> > > I can't speak for anyone else, but for me, nice to have<br>
> you here. :)<br>
> > ><br>
> > > ---- Nick<br>
> > ><br>
> > >> thanks,<br>
> > >> Summer<br>
> > >><br>
> > >><br>
> > >> Summer Long<br>
> > >> OpenStack Documentation<br>
> > >> Engineering Content Services<br>
> > >><br>
> > >> Red Hat Asia Pacific<br>
> > >> Brisbane, Australia<br>
> > >> <a href="mailto:slong@redhat.com">slong@redhat.com</a> <mailto:<a href="mailto:slong@redhat.com">slong@redhat.com</a>><br>
> <mailto:<a href="mailto:slong@redhat.com">slong@redhat.com</a> <mailto:<a href="mailto:slong@redhat.com">slong@redhat.com</a>>><br>
> > <mailto:<a href="mailto:slong@redhat.com">slong@redhat.com</a> <mailto:<a href="mailto:slong@redhat.com">slong@redhat.com</a>><br>
> <mailto:<a href="mailto:slong@redhat.com">slong@redhat.com</a> <mailto:<a href="mailto:slong@redhat.com">slong@redhat.com</a>>>><br>
> > >><br>
> > >><br>
> > >><br>
> > >><br>
> > >> _______________________________________________<br>
> > >> Openstack-docs mailing list<br>
> > >> <a href="mailto:Openstack-docs@lists.openstack.org">Openstack-docs@lists.openstack.org</a><br>
> <mailto:<a href="mailto:Openstack-docs@lists.openstack.org">Openstack-docs@lists.openstack.org</a>><br>
</div></div>> > <mailto:<a href="mailto:Openstack-docs@lists.openstack.org">Openstack-docs@lists.openstack.org</a><br>
<div class="im">> <mailto:<a href="mailto:Openstack-docs@lists.openstack.org">Openstack-docs@lists.openstack.org</a>>><br>
> > >><br>
> <a href="http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs" target="_blank">http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs</a><br>
> > >><br>
> > ><br>
> > > _______________________________________________<br>
> > > Openstack-docs mailing list<br>
> > > <a href="mailto:Openstack-docs@lists.openstack.org">Openstack-docs@lists.openstack.org</a><br>
> <mailto:<a href="mailto:Openstack-docs@lists.openstack.org">Openstack-docs@lists.openstack.org</a>><br>
</div>> > <mailto:<a href="mailto:Openstack-docs@lists.openstack.org">Openstack-docs@lists.openstack.org</a><br>
<div class="im">> <mailto:<a href="mailto:Openstack-docs@lists.openstack.org">Openstack-docs@lists.openstack.org</a>>><br>
> > ><br>
> <a href="http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs" target="_blank">http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs</a><br>
> ><br>
> ><br>
> > _______________________________________________<br>
> > Openstack-docs mailing list<br>
> > <a href="mailto:Openstack-docs@lists.openstack.org">Openstack-docs@lists.openstack.org</a><br>
> <mailto:<a href="mailto:Openstack-docs@lists.openstack.org">Openstack-docs@lists.openstack.org</a>><br>
</div>> > <mailto:<a href="mailto:Openstack-docs@lists.openstack.org">Openstack-docs@lists.openstack.org</a><br>
<div class="im">> <mailto:<a href="mailto:Openstack-docs@lists.openstack.org">Openstack-docs@lists.openstack.org</a>>><br>
> > <a href="http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs" target="_blank">http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs</a><br>
> ><br>
> ><br>
> ><br>
> ><br>
> > --<br>
> > Anne Gentle<br>
> > <a href="mailto:annegentle@justwriteclick.com">annegentle@justwriteclick.com</a><br>
> <mailto:<a href="mailto:annegentle@justwriteclick.com">annegentle@justwriteclick.com</a>><br>
</div>> <mailto:<a href="mailto:annegentle@justwriteclick.com">annegentle@justwriteclick.com</a><br>
<div class="im">> <mailto:<a href="mailto:annegentle@justwriteclick.com">annegentle@justwriteclick.com</a>>><br>
><br>
><br>
><br>
><br>
> --<br>
> Anne Gentle<br>
</div>> <a href="mailto:annegentle@justwriteclick.com">annegentle@justwriteclick.com</a> <mailto:<a href="mailto:annegentle@justwriteclick.com">annegentle@justwriteclick.com</a>><br>
<br>
</blockquote></div><br></div></div>