<div dir="ltr"><br><div class="gmail_extra"><br><br><div class="gmail_quote">On Mon, Jul 1, 2013 at 9:08 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: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>
</div><div><div class="h5">> <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 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 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 useless"[1].<br>
><br>
> The aim that I remember was to create a Configuration 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 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 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 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 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 Guide.<br>
> - We agreed at the Summit that more detailed analysis was required. This<br>
> is what we're doing now.<br>
><br>
> Hope that clears up any confusion.<br>
<br>
</div></div>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>
<div class="im"><br>
<br></div></blockquote><div><br></div><div style>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.</div>
<div style><br></div><div style>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. </div>
<div style>Anne</div><div><br></div><div> </div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex"><div class="im">
> Nick specifically is doing an analysis of admin guides. Summer can you<br>
> and Nick work together on a detailed outline and analysis? One question<br>
> he is working through is whether "OpenStack Administration" is 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 projects,<br>
> Block Storage and Networking respectively. This is my line of<br>
> questioning in the survey I sent out recently. [2] Specifically, these<br>
> two questions:<br>
> 4. As a reader, would you prioritize project docs over overarching<br>
</div>> docsor vice-versa? Why?<br>
<div><div class="h5">><br>
><br>
> 5. As a project maintainer, which docs would you value more highly,<br>
> combined solutions docs or docs specific and detailed for your project? Why?<br>
><br>
> I know we have a lot more to work through to get to the right 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 questions<br>
> are tangled together and we'll all work together to straighten 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. That's<br>
> why I'm very glad you're asking early, Summer, and that we're all able<br>
> to input our findings as we go.<br>
><br>
> Hopefully I'm detangling and not entangling! Let's talk more about it at<br>
> next week's meeting and on this list.<br>
> Anne<br>
><br>
> [2]<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 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 component guides?<br>
> ><br>
> > Hi, Summer --<br>
> ><br>
> > I've actually been pretty quiet here, but I'm currently 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 about<br>
> how we<br>
> > might work together on this?<br>
> ><br>
> >> I'm new to working with Open Source docs (previously 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 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>
</div></div>> <mailto:<a href="mailto:slong@redhat.com">slong@redhat.com</a> <mailto:<a href="mailto:slong@redhat.com">slong@redhat.com</a>>><br>
<div class="im">> >><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>
</div>> <mailto:<a href="mailto:Openstack-docs@lists.openstack.org">Openstack-docs@lists.openstack.org</a>><br>
<div class="im">> >> <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>
</div>> <mailto:<a href="mailto:Openstack-docs@lists.openstack.org">Openstack-docs@lists.openstack.org</a>><br>
<div class="im">> > <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>
</div>> <mailto:<a href="mailto:Openstack-docs@lists.openstack.org">Openstack-docs@lists.openstack.org</a>><br>
<div class="im">> <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>
</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><br clear="all"><div><br></div>-- <br>Anne Gentle<br><a href="mailto:annegentle@justwriteclick.com" target="_blank">annegentle@justwriteclick.com</a>
</div></div>