<div dir="ltr">Hello everyone,<div><br></div><div style>Here's the preliminary blueprint: <a href="https://wiki.openstack.org/wiki/Blueprint-os-admin-docs">https://wiki.openstack.org/wiki/Blueprint-os-admin-docs</a>.</div>
<div style><br></div><div style>I need to clean it up a little, but most of it is there. </div><div style><br></div><div style>Please do send me some feedback regarding the layout, purpose and the next steps.</div><div style>
<br></div><div style>Thanks!</div><div style><br></div><div style>Nermina</div><div style><br></div><div style><br></div></div><div class="gmail_extra"><br><br><div class="gmail_quote">On Fri, Aug 23, 2013 at 1:35 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:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex"><div dir="ltr"><br><div class="gmail_extra"><br><br><div class="gmail_quote"><div class="im">On Fri, Aug 23, 2013 at 11:46 AM, Nermina Miller <span dir="ltr"><<a href="mailto:nerminamiller@gmail.com" target="_blank">nerminamiller@gmail.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 dir="ltr">Just a quick note that I've begun working on the blueprint revision. I'm using the version posted by Nick (<a href="https://wiki.openstack.org/wiki/Blueprint-os-admin-docs" target="_blank">https://wiki.openstack.org/wiki/Blueprint-os-admin-docs</a>). I will be matching up the remaining parts with that ToC. - Nermina</div>
<div class="gmail_extra"><br><br></div></blockquote><div><br></div></div><div>Good thinking. A patch is nice but a blueprint helps us all see the history. To me, that ToC is still too big... can you remove install and config info and then match up remaining parts? </div>
<div><br></div><div>Also I want Diane to get further on the Admin User Guide so we have a good chance to step back and look at that. I know you've been in there, do you see a difference between an Admin Guide and an Admin User Guide? </div>
<div><br></div><div>For next tasks per guide here's what I envision:</div><div><br></div><div>Nermina: Pare down the "OpenStack Admin Guide" outline/blueprint based on what's leftover now</div><div>Action: Find someone to pare down the Network Admin Guide -- does config info remain in that specific guide? Not sure. Anne to ask Edgar.</div>
<div>Anne: Remove the Object Storage Admin Guide folder and move relevant info to new homes. <a href="https://bugs.launchpad.net/openstack-manuals/+bug/1216037" target="_blank">https://bugs.launchpad.net/openstack-manuals/+bug/1216037</a><br>
</div><div>Diane: Complete Admin User Guide (prior to Docs Boot Camp)<br></div><div><div>Done: Pare down the Block Storage Admin Guide.<br></div></div><div><br></div><div>More embedded below. </div><div><div class="h5"><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 class="gmail_extra"><div class="gmail_quote"><div><div>On Wed, Aug 21, 2013 at 10:10 PM, Anne Gentle <span dir="ltr"><<a href="mailto:annegentle@justwriteclick.com" target="_blank">annegentle@justwriteclick.com</a>></span> wrote:<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><div><div dir="ltr">Hi all, <div>
I wanted to circle back on these items. I've been in touch with the PTLs and their teams, I wrote to the dev list, then I thought some more, and it has taken a while. </div>
<div><br></div><div class="gmail_extra"><div class="gmail_quote"><div><div>
On Sun, Aug 4, 2013 at 12:12 PM, Anne Gentle <span dir="ltr"><<a href="mailto:annegentle@justwriteclick.com" target="_blank">annegentle@justwriteclick.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 dir="ltr"><br><div class="gmail_extra"><br><br><div class="gmail_quote"><div><div>On Thu, Aug 1, 2013 at 3:52 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"><div>On 02/08/13 06:43, Anne Gentle wrote:<br>
><br>
><br>
><br>
> On Thu, Aug 1, 2013 at 3:27 PM, Tom Fifield <<a href="mailto:tom@openstack.org" target="_blank">tom@openstack.org</a><br>
</div><div><div>> <mailto:<a href="mailto:tom@openstack.org" target="_blank">tom@openstack.org</a>>> wrote:<br>
><br>
> > The titles that we'll release Oct 17th, regardless of number of<br>
> bugs, are:<br>
> ><br>
> > - Compute Administration Guide (contains Identity and Images)<br>
><br>
><br>
> I disagree with releasing inaccurate information, and would instead opt<br>
> for incomplete documentation. Very important distinctions in types of<br>
> bugs - those that denote something missing and those that denote<br>
> something is wrong.<br>
><br>
> Then, I believe that just verifying the accuracy of the information in<br>
> the Compute Administration Guide (i.e. we don't have bugs for many areas<br>
> that are potentially wrong) is going to take a lot of effort, and I have<br>
> yet to see where this will come from.<br>
><br>
> My suggestion would be to focus on the documents that we can make<br>
> accurate prior to release and publish the 'full library' at a later<br>
> date.<br>
><br>
><br>
> So nice to have you in our time zone Tom. :)<br>
><br>
> I think the actual design layout will help us realize that "releases"<br>
> will look different for Havana. We won't have that redesign for a few<br>
> weeks, so we're talking abstractedly but have concrete views already<br>
> cemented.<br>
><br>
> I'm asserting that the only guides that we can ever guarantee to be<br>
> synchronized with released code are install and config (automated). All<br>
> others are released continuously. Yes it means inaccuracies may exist<br>
> but bugs exist in the code too. We can certainly leave out entire<br>
> sections or chapters if they're just too buggy.<br>
><br>
> I don't think that there will be a Havana Compute Administration Guide<br>
> on October 17th, there will be a "continuously published from master"<br>
> Compute Administration Guide.<br>
><br>
> The ownership is what concerns me -- Neutron "owns" their Networking<br>
> Admin Guide, so does Cinder. Nova and Swift, not so much ownership. So<br>
> are you proposing removal of Compute Admin Guide and Object Storage<br>
> Admin Guide until owners step up? I can certainly consider that here.<br>
><br>
> I think we agree -- its just that the full Havana library is just two<br>
> books. The rest of the books are on the shelf with a published date on<br>
> them. I hope the redesign will help users understand this.<br>
<br>
</div></div>Using Jet Lag to advantage :)<br>
<br>
So yes - I am leaning towards 'not having' as a consideration.<br>
<br></blockquote><div><br></div><div><br></div></div></div><div>So here's where I'm at while mulling it over for a while... I don't think we get rid of the Admin Guide titles, yet. (Titles. Contents I can completely delete or move without a problem.) I think we delete contents until only accurate content is in them. But, we also need to have this conversation on the openstack-dev list. I started it here on openstack-docs but these are documents that belong to everyone and we need to expand our conversation. I'll get that post out Monday. </div>
</div></div></div></blockquote><div><br></div></div></div><div>I got our release manager, Thierry Carrez's response to my post to the openstack-dev mailing list as a good indicator that going to continuous release for many books would be just fine. [1]</div>
<div><br></div><div>I also went to four team meetings to get input directly from the teams themselves for these four titles:</div><div><br></div><div><div><span style="font-family:arial,sans-serif;font-size:13px"> - Block Storage Service Administration Guide</span><br style="font-family:arial,sans-serif;font-size:13px">
</div><div><span style="font-family:arial,sans-serif;font-size:13px"> - Compute Administration Guide (contains Identity and Images)</span><br style="font-family:arial,sans-serif;font-size:13px"></div><div>
<span style="font-family:arial,sans-serif;font-size:13px"> - Networking Administration Guide</span><br style="font-family:arial,sans-serif;font-size:13px">
<span style="font-family:arial,sans-serif;font-size:13px"> - Object Storage Administration Guide</span><br></div></div><div><br></div><div>I'll go through each in turn.</div><div><div><br></div><div><span style="font-size:13px;font-family:arial,sans-serif"> - Block Storage Service Administration Guide</span></div>
</div><div>The team is fine with putting their config and install info into other books, and that leaves only the "Managing Volumes" chapter in this title. This patch does this reorg work: <a href="https://review.openstack.org/#/c/40451/" target="_blank">https://review.openstack.org/#/c/40451/</a>. After that patch goes through, if we can find a home for "Managing Volumes," perhaps in the Ops Guide, not sure yet, then we can eliminate this separate book. Sorry that the patch has gotten a little large, it wasn't my intent (to have that large of a patch). Hopefully this explanation helps.<br>
</div><div><div><br style="font-size:13px;font-family:arial,sans-serif"></div></div></div></div></div></div></div></blockquote></div></div></blockquote><div><br></div></div></div><div>This patch is now merged.</div><div class="im">
<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 class="gmail_extra"><div class="gmail_quote"><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><div>
<div dir="ltr"><div class="gmail_extra"><div class="gmail_quote"><div><div><span style="font-size:13px;font-family:arial,sans-serif"> - Compute Administration Guide (contains Identity and Images)</span></div><div>
<br></div></div><div>
The nova team is also fine with whatever we as a doc team think is best. Lots of trust there! :) We've done a lot of gutting of this guide, and it still has some content that doesn't have a home. Specifically:</div>
<div>Overall architecture</div><div>Identity Management</div><div>Image Management</div><div>Networking with nova-network</div><div>System Administration</div><div>OpenStack Interfaces</div><div>Security Hardening</div><div>
OpenStack Compute Automated Installations</div><div>Compute Tutorials</div><div>Troubleshooting</div><div><br></div><div>I think these can all find other homes, but I'm not exactly sure where yet. The patch I refer to above does some of the moving as well. </div>
<div><br style="font-size:13px;font-family:arial,sans-serif"></div></div></div></div></div></div></blockquote></div></div></blockquote><div><br></div></div><div>Nermina, hopefully you find new homes for these. These can also be deleted if they are outdated and inaccurate.</div>
<div class="im">
<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 class="gmail_extra"><div class="gmail_quote">
<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><div><div dir="ltr"><div class="gmail_extra">
<div class="gmail_quote"><div>
<span style="font-size:13px;font-family:arial,sans-serif"> - Networking Administration Guide</span></div><div>This team is also fine with removing config information and placing it in the Config Reference. However, this is one guide that I'm not convinced we should completely eliminate. It contains use cases for configuration and a high availability chapter and some plugin scenarios that aren't any where else. It's possible the use cases and "Under the Hood" could go into the Configuration Reference, but there are also advanced ops features like logging, notifications, and quotas in this guide. The neutron doc bug is used for 7 doc bugs, so compared to nova's 100+ doc bugs, is this guide actually in okay shape to keep as its own book. It seems like it to me but I want more input. What do you all think?</div>
<div>
<div><br></div></div></div></div></div></div></div></blockquote></div></div></blockquote><div><br></div></div><div>I'm going to ask Edgar Magana if he can take a look. I triaged more doc bugs for neutron/quantum and there's more like 20 doc bugs so they're not in really great shape. </div>
<div class="im">
<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 class="gmail_extra"><div class="gmail_quote">
<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><div><div dir="ltr"><div class="gmail_extra">
<div class="gmail_quote"><div><div></div><div><span style="font-size:13px;font-family:arial,sans-serif"> - Object Storage Administration Guide</span><br></div></div><div>This team is fine with removal from openstack-manuals once all the info is correctly placed. For example, Configuring Object Storage with the S3 API needs to go to the Configuration Reference. Tom has a WIP patch going on right now that scrapes their sample configs and puts them into tables, thankfully getting rid of the <a href="http://raw.github.com" target="_blank">raw.github.com</a> links I had placed, <a href="https://review.openstack.org/#/c/43032/" target="_blank">https://review.openstack.org/#/c/43032/</a>. Thanks Tom!</div>
<div><br></div><div>These are the chapters and sections that need to find a new home:</div>
OpenStack Object Storage Tutorials<div>Object Storage Monitoring</div><div><br></div><div>All this said, the remaining content of three Admin guides could be either: </div><div>the starting point for an OpenStack Administration Guide</div>
<div>
or</div><div>moved into the Operations Guide. </div><div><br></div><div>Nick and/or Nermina, are you willing to do a patch for review that brings the remaining parts into an OpenStack Admin guide or is that too "Frankendoc" (trying to revive dead parts to make a whole?) Or do these final parts belong in the Operations Guide? We have about 2 and a half weeks before Docs Boot Camp, seems like enough time to get a WIP patch to see how it looks. Interested? </div>
<div><br></div></div></div></div></div></div></blockquote></div></div></blockquote><div><br></div></div><div>Yeah maybe I'm getting ahead of myself and really I want a blueprint and outline not a patch quite yet. :) Thanks Nermina!</div>
<span class="HOEnZb"><font color="#888888">
<div>Anne</div><div> </div></font></span><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 class="gmail_extra">
<div class="gmail_quote">
<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 class="im"><div><div><div dir="ltr"><div class="gmail_extra">
<div class="gmail_quote"><div></div><div>Thanks again for patience and all this analysis. I do realize I haven't attended keystone and glance weekly meetings, but their portions are small and I wanted to get this out now. I'll talk to them next.</div>
<div><br></div><div>Thanks,</div><div><br></div><div>Anne</div><div><br></div><div>1. <a href="http://lists.openstack.org/pipermail/openstack-dev/2013-August/013352.html" target="_blank">http://lists.openstack.org/pipermail/openstack-dev/2013-August/013352.html</a></div>
<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 dir="ltr"><div class="gmail_extra"><div class="gmail_quote">
<div><br></div><div>Also, soon we'll have more info about the redesign and we can revisit then again. Hopefully this week I'll have the draft redesign which fixes the problem with people reading outdated info because the release info is hard to find. (bug <span style="color:rgb(102,102,102);font-family:Ubuntu,'Bitstream Vera Sans','DejaVu Sans',Tahoma,sans-serif;font-size:12px;line-height:18px">1191447</span>) <a href="https://bugs.launchpad.net/openstack-manuals/+bug/1191447" target="_blank">https://bugs.launchpad.net/openstack-manuals/+bug/1191447</a> This redesign may help us shape the title list as well. </div>
<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">
I disagree that we should be publishing inaccurate information.<br>
If we can't verify that it's OK, it shouldn't be on an official document<br>
on <a href="http://openstack.org" target="_blank">openstack.org</a>.<br></blockquote><div><br></div></div><div>This statement is not one I can back or support. We need to be careful about throwing around words like "official" because there are a lot of grassroots efforts around docs, training, HA, and I do not want to squelch those efforts or discourage them in any way by raising the bar way too high for contributing to <a href="http://docs.openstack.org" target="_blank">docs.openstack.org</a> or <a href="http://api.openstack.org" target="_blank">api.openstack.org</a>. I can support statements like "we strive for accuracy and test as throughly as possible" but I cannot back anything strongly stated about "official" because the Board and the TC are still working through "what is core?" and other such important questions. Read more at <a href="http://robhirschfeld.com/2013/07/24/what-is-core-strawman/" target="_blank">http://robhirschfeld.com/2013/07/24/what-is-core-strawman/</a> if you want some background, it's important we all understand what we're working through as a community. </div>
<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">
<br>
What needs to happen, in my opinion, is a complete gutting of the<br>
guides, and sections only added back in when they have been verified to<br>
be technically accurate (potentially also copyedited, scoped and<br>
structured ^_^). I disagree that just because something is 'continously<br>
published' means that this step can be avoided.<br>
<br></blockquote><div><br></div></div><div>Gutting is happening now. I believe the Compute Admin Guide especially will be quite gutted.</div><div><br></div><div>Hope this helps - thanks for keeping the feedback going and look for the discussion with the wider community this week.</div>
<div>Anne</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">
Regards,<br>
<br>
<br>
Tom<br>
<br>
<br>
<br>
<br><span><font color="#888888">
</font></span></blockquote></div><span><font color="#888888"><br><br clear="all"><div><br></div>-- <br>Anne Gentle<br><a href="mailto:annegentle@justwriteclick.com" target="_blank">annegentle@justwriteclick.com</a>
</font></span></div></div>
</blockquote></div></div><span><font color="#888888"><br></font></span></div></div>
<br></div></div></div><div class="im"><div>_______________________________________________<br>
Openstack-docs mailing list<br>
<a href="mailto:Openstack-docs@lists.openstack.org" target="_blank">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></div></div></blockquote></div><div class="im"><br><br clear="all"><div><br></div>-- <br><div><div dir="ltr">Thank you!<div><br></div><div>Nermina Miller</div><div>Tech Writer and Editor</div></div></div></div></div>
</blockquote></div>
</div></div>
</blockquote></div><br><br clear="all"><div><br></div>-- <br><div dir="ltr">Thank you!<div><br></div><div>Nermina Miller</div><div>Tech Writer and Editor</div></div>
</div>