<div dir="ltr"><br><div class="gmail_extra"><br><br><div class="gmail_quote">On Wed, Dec 11, 2013 at 5:31 PM, Anne Gentle <span dir="ltr"><<a href="mailto:anne@openstack.org" target="_blank">anne@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"><div dir="ltr">







<p>Thanks to new doc patchers Shilla Saebi and Thomas Herve for their clean up work, especially for the Identity API docs and Heat install!<br></p><p>Be ready for 12/20/13 Doc Bug Day! Looking forward to it.</p>
<p>1. In review and merged this past week:</p>
<p>The Install Guide is still the most worked-on document. I'd like to shift from that now that we're past milestone-1 and work harder on the Cloud Administrator Guide and Operations Guide, to separate out items from the Configuration Reference that are "how to" and move them to the Cloud Administrator Guide. Nermina made progress on the Cloud Administrator Guide additions from the Configuration Reference, her analysis is here: <a href="http://lists.openstack.org/pipermail/openstack-docs/2013-December/003459.html" target="_blank">http://lists.openstack.org/pipermail/openstack-docs/2013-December/003459.html</a></p>


<p>Lana Brindley was in Texas this week, and she's going to take on maintenance of the User Guide and Admin User Guide with some additions of scripts that are common user/admin user tasks with CLIs. She's also looking into our processes and reviews and making good strides towards bringing in developer teams for reviews after they use the DocImpact flag. Thanks Lana!<br>


</p>
<p>2. High priority doc work:</p>
<p>To me, one high priority is to get the config options done for milestone 1 release.</p><p>Another priority is for me to write a "content spec" for each book that we currently maintain, so that incoming projects can easily "plug in" to each deliverable. If I had to write a short description of each book, it'd be:</p>


<p>Installation Guide - Describes a manual install process for multiple distributions including CentOS, Debian, Fedora, OpenSUSE, RedHat Enterprise Linux, SUSE Enterprise Linux, and Ubuntu.</p><p>Configuration Reference - Contains a reference listing of all configuration options for core and integrated OpenStack services.</p>


<p>Cloud Administrator Guide - Contains how-to information for managing an OpenStack cloud as needed for your use cases, described in this document.</p><p>High Availability Guide - Describes potential strategies for making your OpenStack services and related controllers and data stores highly available.</p>


<p>Operations Guide - Offers information for designing and operating OpenStack private or public clouds plus best practices for day-to-day operations.</p><p>Security Guide - Provide best practices and conceptual information about securing an OpenStack cloud</p>


<p>Virtual Machine Image Guide - Shows you how to obtain, create, and modify virtual machine images that are compatible with OpenStack.</p>End User Guide - Shows OpenStack end users how to create and manage resources in an OpenStack cloud with the OpenStack dashboard and OpenStack client commands.<br>


<br>Admin User Guide - Shows OpenStack admin users how to create and manage resources in an OpenStack cloud with the OpenStack dashboard and OpenStack client commands.<div><br></div><div>API Quick Start - A brief overview of how to send requests to endpoints for OpenStack services.</div>


<div><br></div><div>I'd like for projects to understand what goes where and be able to write sections that fit into these titles. I'm not recommending that you create your own title, but understand where your section can go in the wider picture of OpenStack docs.<br>


<p>3. Doc work going on that I know of:</p>
<p>See below for the developmental edit of the O'Reilly edition of the Operations Guide.</p><p>Shaun's working on the autodoc for configuration option tables for the icehouse-1 milestone.</p>
<p>4. New incoming doc requests:</p>
<p>The Triple-O team would like to talk about how to plug into the OpenStack existing docs. Feel free to reach out on details, while we are going to stick with the manual install for this release (Icehouse), perhaps the Triple-O team can get a head start. Open to ideas after hearing from them in the weekly project meeting.</p>



<p>5. Doc tools updates:</p></div></div></blockquote>I left out an important update for doc tools -- Sphinx 1.2 was just released and it is incompatible with distutils in python 2.7. This means that all projects need to fix their doc builds either by subscribing to openstack/requirements which already has the correct version of Sphinx pinned, or by pinning sphinx>=1.1.2,<1.2 in your own requirements file. See the thread on openstack-dev at <a href="http://lists.openstack.org/pipermail/openstack-dev/2013-December/021863.html">http://lists.openstack.org/pipermail/openstack-dev/2013-December/021863.html</a> or ask a friendly infrastructure dev for help.</div>

<div class="gmail_quote">Anne<br><div> </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"><div dir="ltr">

<div>
<p>The infra team is working on ways to version and deploy the clouddocs-maven-plugin (wow, that's verbing a noun). </p>
<p>6. Other doc news:</p><p>The development edit for the Operations Guide from O'Reilly has begun, and by tomorrow we should have input on a few more chapters. Here are some overarching comments from Brian Anderson you may like to help us dig into:</p>


<p>---</p><p><span style="font-family:arial,sans-serif;font-size:13px">- an expanded Preface which situates the Operations Guide in relation to other, related guides (like the Admin guide you mentioned). A taxonomy of user roles would be helpful here.</span><br style="font-family:arial,sans-serif;font-size:13px">


<span style="font-family:arial,sans-serif;font-size:13px">- an introductory chapter about OpenStack, showing, in particular, a high-level view of an OpenStack deployment and the different sorts of components. There should be an emphasis on how the components work together. Some institution-level suggestions would perhaps be helpful here (what your organization should bear in mind when using OpenStack)</span><br style="font-family:arial,sans-serif;font-size:13px">


<span style="font-family:arial,sans-serif;font-size:13px">- a sneak peek of Icehouse (in the preface? or as an appendix?)</span><br style="font-family:arial,sans-serif;font-size:13px"><span style="font-family:arial,sans-serif;font-size:13px">- more content focusing on how to upgrade from one version to another (maybe this would be a new chapter?)</span><br style="font-family:arial,sans-serif;font-size:13px">


<br style="font-family:arial,sans-serif;font-size:13px"><span style="font-family:arial,sans-serif;font-size:13px">As I mentioned, the book is quite "clean". However, we can aim it at our audience a bit more. As it stands, the book contains a lot of tactics but not a lot of strategy. What are some broad considerations that our audience should bear in mind when operating OpenStack?</span><br>


</p><p><span style="font-family:arial,sans-serif;font-size:13px">---</span></p><p><span style="font-family:arial,sans-serif;font-size:13px">Contact me if you have an interest in a specific area for the Ops Guide. </span></p>


<p><span style="font-family:arial,sans-serif;font-size:13px">Also, we welcome the OPW interns who will be working on docs - Miranda Zhang will be working with Diane Fleming, and Cindy Pallares will be working on Marconi docs with Flavio Percoco. Welcome new interns!</span></p>


</div></div>
</blockquote></div><br></div></div>