<div dir="ltr"><br><div class="gmail_extra"><br><br><div class="gmail_quote">On Mon, Jul 1, 2013 at 7:59 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:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex">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 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></blockquote><div><br></div><div style>A couple of reasons for this addition back. </div><div style>- 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. </div>
<div style>- 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. </div>
<div style>- 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. </div>
<div style>- We agreed at the Summit that more detailed analysis was required. This is what we're doing now. </div><div style><br class="">Hope that clears up any confusion. <br></div><div style><br></div><div style>
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?" </div>
<div style><br></div><div style>My current thinking is:</div><div style>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:</div>
<div style><span style="color:rgb(83,83,83);font-family:'andale mono','lucida console',monospace;font-size:12px;line-height:18px;white-space:pre-wrap">4. As a reader, would you prioritize project docs over overarching docs</span><span style="color:rgb(83,83,83);font-family:'andale mono','lucida console',monospace;font-size:12px;line-height:18px;white-space:pre-wrap"> or vice-versa? Why?</span></div>
<pre style="margin-top:1.5em;margin-bottom:1.5em;padding:0px;border:0px;font-size:12px;font-family:'andale mono','lucida console',monospace;vertical-align:baseline;white-space:pre-wrap;line-height:18px;color:rgb(83,83,83)">
5. As a project maintainer, which docs would you value more highly,
combined solutions docs or docs specific and detailed for your project? Why?</pre><div style>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.</div>
<div style><br></div><div style>Hopefully I'm detangling and not entangling! Let's talk more about it at next week's meeting and on this list. </div><div style>Anne</div><div style><br></div><div style>[2] <a href="http://lists.openstack.org/pipermail/openstack-docs/2013-June/002037.html">http://lists.openstack.org/pipermail/openstack-docs/2013-June/002037.html</a></div>
<div style><br></div><div style><br></div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex">
<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>
<div class=""><div class="h5"><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 like to<br>
>> help with the OS Admin Guide.<br>
>> Can you tell me where I can contribute to its design? Steve 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 promise! --<br>
> would you like to get together sometime this week to chat about 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 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>
>><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>
>> <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>
> <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>
<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>
</div></div></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>