<div dir="ltr">Hi all, <div>Sorry it took me so long to circle back to this thread, but I think Summer's analysis is right but I have some nuanced responses. </div><div><br></div><div>I've also asked Nermina to finalize her research next week, so stay tuned.</div>
<div><br></div><div>More below.</div><div class="gmail_extra"><br><br><div class="gmail_quote">On Wed, Jul 10, 2013 at 11:23 PM, Summer Long <span dir="ltr"><<a href="mailto:slong@redhat.com" target="_blank">slong@redhat.com</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 text="#000000" bgcolor="#FFFFFF">
Hi Anne,<br>
I know I don't have street cred yet, but here's my offering.<br></div></blockquote><div><br></div><div style>Hee. I love street cred. You're gaining it all the time.</div><div style> </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 text="#000000" bgcolor="#FFFFFF">
<br>
<b>Administration Guide / Admin User Guide</b><br>
Am thinking that the biggest problem is one of audience. The
restructure blueprint says that the 'Administration Guide' is for
deployers and not for the administrative user. And it says that one
of the tasks of a deployer is to 'run' the cloud. <br>
This feels like a mixed target, the deployer doesn't necessarily
stick around to administer what's been deployed. (Is this definition
a result of the Ops Guide? That too could be divied up now that the
suite is growing.)<br>
<br></div></blockquote><div><br></div><div style>When we talked about audience day one of the sprint, 2-3 of the guys in there wanted a book they could hand over to their newest hires and ask them to learn enough about OpenStack to help out. There's a "Lay of the Land" page dedicated to telling people how to learn about their own cloud. <a href="http://docs.openstack.org/trunk/openstack-ops/content/lay_of_the_land.html">http://docs.openstack.org/trunk/openstack-ops/content/lay_of_the_land.html</a> </div>
<div style><br></div><div style>Knowing Tom wrote the original restructure blueprint, I've gotta ask, Tom, who's the deployer? Same as the administrator?</div><div style><br></div><div style>Also we decided day one to split the guide into Architecture decisions and Day to day administration. I have an emailed/tweeted request to do a Design Guide next, which would be architecture decisions. Based on the people who worked on the Ops Guide, the deployer usually does run the cloud, but I do want that confirmed by Nirmina's research, and by asking Tom to chime in.</div>
<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 text="#000000" bgcolor="#FFFFFF">
With this definition of deployer, of course the Admin guide would be
huge, including both deployment and management tasks. And is why the
Admin Guide blueprint is so large, including information on
installation and configuration in each project chapter. If you
clearly separate the audience, I believe there should be only one
Administration guide, for the person sitting down to manage the
beast after it's been deployed.<br></div></blockquote><div><br></div><div style>Agreed. I think this was the original intent of the Ops Guide. Another tidbit about the Ops Guide that might shape our body of work is that the Foundation is going to hire O'Reilly to do a custom edit the guide, and there will be an O'Reilly edition of the Ops Guide. We still can do anything we want to it, it is our content, so the difference between the O'Reilly edition and our edition may be academic only. But I'm very curious to hear what pro-level editors at O'Reilly have to say about the contents and audience of the Ops Guide. Stay tuned this fall.</div>
<div style> </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 text="#000000" bgcolor="#FFFFFF">
<br>
IMVHO, the Admin User Guide could be the 4.0 Administration Guide
(with its clear focus on admin tasks), with the next release
including the broader admin tasks from Nick's specification
(security, troubleshooting, etc).<br></div></blockquote><div><br></div><div style>I think the main concern I have with Nick's outline and specification is the inclusion of install/deploy. As we've seen from the install thread, most people are using distros. </div>
<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 text="#000000" bgcolor="#FFFFFF">
<br>
<b>Project Admin Guides / Single Admin Guide</b><br>
If it is at all feasible, I'd keep the project admin guides going.
And use xi:includes to bring their content into the Administration
Guide where relevant. There will be inconsistency across project
guides, but:<br>
--They are useful for component-focused issues.<br>
--Detailed, advanced material can be introduced which might be out
of place in an overarching admin guide.<br>
--Dev folk will always be more interested in producing content for
their own project doc (and then it can be referenced elsewhere).<br>
<br></div></blockquote><div><br></div><div style>Yep, agreed on all fronts. </div><div style><br></div><div style>I had a conversation this week with a Swift developer (hi Chuck!) about separating Admin info out of their dev docs and trying to identify more info that can go into the Object Storage Admin guide. He's certainly up for updating and cleaning up but we'd love to identify someone who would just love to dig into that. One area we identified is that the Swift devs aren't using DocImpact as effectively as we'd like. For example, an Apache proxy server implementation is now available but not documented in openstack-manuals, only in the swift repo. So yes, project teams want to work on project doc and get support for admin docs. </div>
<div style><br></div><div style>One missing Admin Guide today is an Identity Admin Guide. It might really be time for this as the administration tasks for keystone continue to add up. Currently it's in /common/ and embedded in the Compute Admin Guide. This is another area that it would be nice to find a doc liaison for the project team.</div>
<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 text="#000000" bgcolor="#FFFFFF">
cheers, Summer<br>
<br>
<div>
<div><font color="#666666">Summer Long<br>
OpenStack Documentation<br>
Engineering Content Services<br>
<br>
Red Hat Asia Pacific<br>
Brisbane, Australia</font><br>
<a href="mailto:slong@redhat.com" target="_blank">slong@redhat.com</a></div>
</div><div class="im">
<br>
<span style>
<div>On 07/11/2013 05:21 AM, Anne Gentle
wrote:<br>
</div>
</span>
<blockquote type="cite">
<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>
<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>
</div>
</blockquote>
<blockquote type="cite">
<div dir="ltr">
<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>
</div>
</blockquote></div>
Nick: Yes. I know that was the goal of the Ops Guide, but I think it
landed in a different, and just as vital, spot. I think a
comprehensive guide makes it possible for someone to avoid getting
lost in a sea of books, as the guide will, well, guide them through.<div class="im"><br>
<blockquote type="cite">
<div dir="ltr"><br>
<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]? <br>
</font></p>
</div>
</blockquote></div>
Nick: Absolutely. What she has planned is a vital look at the
essentials.
<div class="im"><blockquote type="cite">
<div dir="ltr">
<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>
</div>
</blockquote></div>
Nick: No. I see it as a progression. start with Diane's book, then
pickup the guide for more in depth understanding of concepts.
<div class="im"><blockquote type="cite">
<div dir="ltr">
<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>
</div>
</blockquote></div>
Nick:Yes.the reality is that those owners are sometimes the best at
this, sometimes not. A guide like this lets us improve where
necessary without ditching the good stuff. Remember we are not
talking about getting rid of the great work you have done (and are
doing) . Just the opposite.
<blockquote type="cite"><div class="im">
<div dir="ltr">
<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 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>
<br>
<fieldset></fieldset>
<br>
</div><pre>_______________________________________________
Openstack-docs mailing list
<a href="mailto:Openstack-docs@lists.openstack.org" target="_blank">Openstack-docs@lists.openstack.org</a>
<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>
</pre>
</blockquote>
<br>
</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>