<div dir="ltr"><p style="font-size:14px;margin:0px;font-family:Calibri"><font color="#000000">Hi all, </font></p><p style="font-size:14px;margin:0px;font-family:Calibri;min-height:17px"><font color="#000000"><br></font></p>

<p style="font-size:14px;margin:0px;font-family:Calibri"><font color="#000000">I'd like to get feedback about the <b>administration</b> portion of our documentation refactoring plan [1], which we overlooked when we created the original documentation restructuring blueprint.[4]</font></p>

<p style="font-size:14px;margin:0px;font-family:Calibri;min-height:17px"><font color="#000000"><br></font></p><p style="font-size:14px;margin:0px;font-family:Calibri"><font color="#000000">tl;dr - We need to make a decision about guides for administrators/operators going forward. Please review the following detailed analysis. </font></p>

<p style="font-size:14px;margin:0px;font-family:Calibri;min-height:17px"><font color="#000000"><br></font></p><p style="font-size:14px;margin:0px;font-family:Calibri"><font color="#000000">Tom, Diane, Nick, Nermina, I, and others have been reviewing the following blueprints for the Havana release:</font></p>

<ol style="font-family:Calibri,sans-serif;font-size:14px"></ol><ul style="font-family:Calibri,sans-serif;font-size:14px"><li style="margin-left:15px"><font color="#000000">[1] restructure documentation blueprint. Describes a plan to restructure the OpenStack documentation. However it did not address Admin Guides.</font></li>

<li style="margin-left:15px"><font color="#000000">[2] modularize admin guide. Recommends a comprehensive administrative guide, with the option of producing smaller project-specific guides. </font></li><li style="margin-left:15px">

<font color="#000000">[3] os-admin-docs. Outlines a comprehensive administration guide that describes everything that an administrator/operator needs to install, deploy, and maintain an OpenStack cluster.</font></li></ul>

<p style="margin:0px;font-size:13px;font-family:Arial"><font color="#000000">I have a few concerns about these blueprints, which is why I'd like <b>more eyes please</b>! To see if we're talking crazy talk. :)</font></p>

<p style="margin:0px;font-size:13px;font-family:Arial"><font color="#000000"><br></font></p><p style="margin:0px;font-size:13px;font-family:Arial"><font color="#000000">My concerns:</font></p><ul style="font-family:Calibri,sans-serif;font-size:14px">

<li style="margin:0px;font-size:13px;font-family:Arial"><font color="#000000">We already have smaller admin guides, which are maintained by project teams. The block storage and networking teams are quite active in maintaining their admin guides. However, the object storage and compute teams are not as invested in their admin guides. So there are issues with having smaller, project-directed guides – lack of consistency, content mismatch, and other issues.</font></li>

<li style="margin:0px;font-size:13px;font-family:Arial"><font color="#000000">The comprehensive administrative guide seems to have the same goals as the existing Operations Guide. In that book sprint, the stated goal was to create a book for new OpenStack cloud operators. </font></li>

<li style="margin:0px;font-size:13px;font-family:Arial"><font color="#000000">We already hear that the Compute Admin Guide is too long. How can a longer guide really be the answer? Lorin pulled out the Image Management chapter to make the <span style="font-size:14px;font-family:Calibri">OpenStack Virtual Machine Image Guide, and the config chapter is moving to the new Configuration Reference</span>. We've been gutting the Compute Admin Guide since the Summit to try to slim it into just a Config Ref and an Admin User Guide. So we're hoping that the gutting will result in a set of books, which then coupled with the Operations Guide, is the fresh-minted OpenStack administrator's ticket to success. </font></li>

<li style="margin:0px;font-size:13px;font-family:Arial"><font color="#000000">The plan for a comprehensive administration guide might not fit with our plans for content modularity and doc ownership. </font></li></ul><p style="margin:0px;font-size:13px;font-family:Arial">

<font color="#000000">The end goal of the admin doc restructuring is to make the Operations Guide, the Admin Guides, and the Config Reference all work well together. We want to avoid redundancy and we want to provide a clear path through the documentation. And we must scope this work correctly for the upcoming October release date.</font></p>

<p style="font-size:14px;margin:0px;font-family:Calibri;min-height:17px"><font color="#000000"><br></font></p><p style="font-size:14px;margin:0px;font-family:Calibri"><b><font color="#000000">Questions:</font></b></p><p style="margin:0px;font-size:13px;font-family:Arial;min-height:15px">

<font color="#000000"><br></font></p><p style="margin:0px;font-size:13px;font-family:Arial"><font color="#000000">Do we need a large, comprehensive Admin guide (now that I see the outline I'm a little daunted)?</font></p>

<p style="margin:0px;font-size:13px;font-family:Arial;min-height:15px"><font color="#000000"><br></font></p><p style="margin:0px;font-size:13px;font-family:Arial"><font color="#000000">Should we create an Admin User Guide with Diane's outline [5]? </font></p>

<p style="margin:0px;font-size:13px;font-family:Arial"><font color="#000000"><br></font></p><p style="margin:0px;font-size:13px;font-family:Arial"><font color="#000000">Does an Admin User Guide eliminate the need for a separate OpenStack Administration Guide?</font></p>

<p style="margin:0px;font-size:13px;font-family:Arial;min-height:15px"><font color="#000000"><br></font></p><p style="margin:0px;font-size:13px;font-family:Arial"><font color="#000000">Should we keep the separate Admin Guides per project? (That brings along the problem with owners and inconsistency.)</font></p>

<p style="margin:0px;font-size:13px;font-family:Arial;min-height:15px"><font color="#000000"><br></font></p><p style="margin:0px;font-size:13px;font-family:Arial"><font color="#000000">Or maybe there is another option or two or eight that we haven't thought of?</font></p>

<div class="im" style="font-family:Calibri,sans-serif;font-size:14px"><p style="margin:0px;font-family:Calibri;min-height:17px"><font color="#000000"><br></font></p><p style="margin:0px;font-family:Calibri"><font color="#000000">Thanks for reading this far! We need more opinions and then a decision for the path forward.</font></p>

<p style="margin:0px;font-family:Calibri"><font color="#000000">Thanks,</font></p><p style="margin:0px;font-family:Calibri"><font color="#000000">Anne</font></p><p style="margin:0px;font-family:Calibri;min-height:17px"><font color="#000000"><br>

</font></p><p style="margin:0px;font-family:Calibri;min-height:17px"><font color="#000000"><br></font></p><p style="margin:0px;font-family:Calibri"><font color="#000000">1 <a href="https://blueprints.launchpad.net/openstack-manuals/+spec/restructure-documentation" target="_blank">https://blueprints.launchpad.net/openstack-manuals/+spec/restructure-documentation</a></font></p>

<p style="margin:0px;font-family:Calibri"><font color="#000000">2 <a href="https://blueprints.launchpad.net/openstack-manuals/+spec/modularize-admin-guide" target="_blank">https://blueprints.launchpad.net/openstack-manuals/+spec/modularize-admin-guide</a></font></p>

<p style="margin:0px;font-family:Calibri"><font color="#000000">3 <a href="https://blueprints.launchpad.net/openstack-manuals/+spec/os-admin-docs" target="_blank">https://blueprints.launchpad.net/openstack-manuals/+spec/os-admin-docs</a></font></p>

<p style="margin:0px;font-family:Calibri"><font color="#000000">4 <a href="https://wiki.openstack.org/w/index.php?title=Blueprint-restructure-documentation&diff=25490&oldid=24528" target="_blank">https://wiki.openstack.org/w/index.php?title=Blueprint-restructure-documentation&diff=25490&oldid=24528</a></font></p>

<p style="margin:0px;font-family:Calibri"><font color="#000000">5 <a href="https://wiki.openstack.org/wiki/Blueprint-restructure-documentation#OpenStack_Admin_User_Guide" target="_blank">https://wiki.openstack.org/wiki/Blueprint-restructure-documentation#OpenStack_Admin_User_Guide</a></font></p>

<p style="margin:0px;font-family:Calibri;min-height:17px"><font color="#000000"><br></font></p><p style="margin:0px;font-family:Calibri"><font color="#000000">More reference information. </font></p><p style="margin:0px;font-family:Calibri;min-height:17px">

<font color="#000000"><br></font></p><p style="margin:0px;font-family:Calibri"><font color="#000000">These are the current titles for the admin audience:</font></p><p style="margin:0px;font-family:Calibri"><font color="#000000">OpenStack Block Storage Service Administration Guide</font></p>

<p style="margin:0px;font-family:Calibri"><font color="#000000">OpenStack Compute Administration Guide</font></p><p style="margin:0px;font-family:Calibri"><font color="#000000">OpenStack Network Service Administration Guide</font></p>

<p style="margin:0px;font-family:Calibri"><font color="#000000">OpenStack Object Storage Administration Guide</font></p><p style="margin:0px;font-family:Calibri"><font color="#000000">OpenStack Operations Guide</font></p>

<p style="margin:0px;font-family:Calibri"><font color="#000000">OpenStack High Availability Guide</font></p><p style="margin:0px;font-family:Calibri"><font color="#000000">OpenStack Virtual Machine Image Guide</font></p>
<p style="margin:0px;font-family:Calibri">
<font color="#000000">OpenStack Security Guide</font></p><p style="margin:0px;font-family:Calibri;min-height:17px"><font color="#000000"><br></font></p><p style="margin:0px;font-family:Calibri"><font color="#000000">These are the additional titles for Havana under consideration:</font></p>

<p style="margin:0px;font-family:Calibri"><font color="#000000">Admin User Guide (sourced from End User Guide)</font></p><p style="margin:0px;font-family:Calibri"><font color="#000000">OpenStack Administration Guide (sourced by combining from modular content)</font></p>

</div></div>