<div dir="ltr">Great... I'm giving this a shot with the keystone patch to see how it looks.</div><div class="gmail_extra"><br><br><div class="gmail_quote">On Thu, Jun 12, 2014 at 12:54 PM, Diane Fleming <span dir="ltr"><<a href="mailto:diane.fleming@rackspace.com" target="_blank">diane.fleming@rackspace.com</a>></span> wrote:<br>
<blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">
<div style="word-wrap:break-word;color:rgb(0,0,0);font-size:14px;font-family:Calibri,sans-serif">
<div>
<div>
<div>+1</div><div class="">
<div>
<div>
<div style="color:rgb(0,0,0)"><font color="rgb(0, 0, 0)" face="Apple Chancery"><i>Diane</i></font></div>
<div style="font-family:Calibri,sans-serif;font-size:14px;color:rgb(0,0,0)">
<font color="rgb(0, 0, 0)"><i>----------------------------------------------</i></font></div>
<div style="font-family:Calibri,sans-serif;font-size:14px;color:rgb(0,0,0)">
<font color="rgb(0, 0, 0)">Diane Fleming</font></div>
<div style="font-family:Calibri,sans-serif;font-size:14px">
<div style="color:rgb(0,0,0)">Software Developer II - US</div>
</div>
<a href="mailto:diane.fleming@rackspace.com" target="_blank">diane.fleming@rackspace.com</a></div>
<div>Cell <a href="tel:512.323.6799" value="+15123236799" target="_blank">512.323.6799</a></div>
<div>Office <a href="tel:512.874.1260" value="+15128741260" target="_blank">512.874.1260</a><br>
<span style="font-family:Calibri,sans-serif">
<div style="font-family:Calibri,sans-serif;font-size:14px">
<div style="color:rgb(0,0,0)">Skype drfleming0227</div>
<div style="color:rgb(0,0,0)">Google-plus <a href="mailto:diane.fleming@gmail.com" target="_blank">diane.fleming@gmail.com</a></div>
</div>
</span></div>
</div>
</div></div>
</div>
<div><br>
</div>
<span>
<div style="font-family:Lucida Grande;font-size:11pt;text-align:left;color:black;BORDER-BOTTOM:medium none;BORDER-LEFT:medium none;PADDING-BOTTOM:0in;PADDING-LEFT:0in;PADDING-RIGHT:0in;BORDER-TOP:#b5c4df 1pt solid;BORDER-RIGHT:medium none;PADDING-TOP:3pt">
<span style="font-weight:bold">From: </span>Matt Kassawara <<a href="mailto:mkassawara@gmail.com" target="_blank">mkassawara@gmail.com</a>><br>
<span style="font-weight:bold">Date: </span>Thursday, June 12, 2014 1:39 PM<br>
<span style="font-weight:bold">To: </span>Diane Fleming <<a href="mailto:diane.fleming@rackspace.com" target="_blank">diane.fleming@rackspace.com</a>><br>
<span style="font-weight:bold">Cc: </span>Anne Gentle <<a href="mailto:anne@openstack.org" target="_blank">anne@openstack.org</a>>, "<a href="mailto:openstack-docs@lists.openstack.org" target="_blank">openstack-docs@lists.openstack.org</a>" <<a href="mailto:openstack-docs@lists.openstack.org" target="_blank">openstack-docs@lists.openstack.org</a>><div>
<div class="h5"><br>
<span style="font-weight:bold">Subject: </span>Re: [Openstack-docs] Installation and configuration section structure<br>
</div></div></div><div><div class="h5">
<div><br>
</div>
<div>
<div>
<div dir="ltr">Since Debian takes a completely different approach for installation and configuration, we should consider separating those instructions into another procedure with OS conditional to ease Tom Goirand's patches and prevent future "jumbling" of
steps.</div>
<div class="gmail_extra"><br>
<br>
<div class="gmail_quote">On Thu, Jun 12, 2014 at 11:06 AM, Diane Fleming <span dir="ltr">
<<a href="mailto:diane.fleming@rackspace.com" target="_blank">diane.fleming@rackspace.com</a>></span> wrote:<br>
<blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">
<div style="word-wrap:break-word;color:rgb(0,0,0);font-size:14px;font-family:Calibri,sans-serif">
<div>
<div>
<div>Matt, </div>
<div><br>
</div>
<div>Sounds right – and I think that can be accomplished without having many small procedures (just for consistency's sake). </div>
<div><br>
</div>
<div>But if it helps to get organized initially, that's a good thing! And some procedures should follow the neutron lead, and have separate procedures for prerequisites, install, configure, and so on.</div>
<div>
<div><br>
</div>
<div><br>
</div>
<div>
<div>
<div style="color:rgb(0,0,0)"><font color="rgb(0, 0, 0)" face="Apple Chancery"><i>Diane</i></font></div>
<div style="font-family:Calibri,sans-serif;font-size:14px;color:rgb(0,0,0)"><font color="rgb(0, 0, 0)"><i>----------------------------------------------</i></font></div>
<div style="font-family:Calibri,sans-serif;font-size:14px;color:rgb(0,0,0)"><font color="rgb(0, 0, 0)">Diane Fleming</font></div>
<div style="font-family:Calibri,sans-serif;font-size:14px">
<div style="color:rgb(0,0,0)">Software Developer II - US</div>
</div>
<a href="mailto:diane.fleming@rackspace.com" target="_blank">diane.fleming@rackspace.com</a></div>
<div>Cell <a href="tel:512.323.6799" value="+15123236799" target="_blank">512.323.6799</a></div>
<div>Office <a href="tel:512.874.1260" value="+15128741260" target="_blank">512.874.1260</a><br>
<span style="font-family:Calibri,sans-serif">
<div style="font-family:Calibri,sans-serif;font-size:14px">
<div style="color:rgb(0,0,0)">Skype drfleming0227</div>
<div style="color:rgb(0,0,0)">Google-plus <a href="mailto:diane.fleming@gmail.com" target="_blank">
diane.fleming@gmail.com</a></div>
</div>
</span></div>
</div>
</div>
</div>
</div>
<div><br>
</div>
<span>
<div style="font-family:Lucida Grande;font-size:11pt;text-align:left;color:black;BORDER-BOTTOM:medium none;BORDER-LEFT:medium none;PADDING-BOTTOM:0in;PADDING-LEFT:0in;PADDING-RIGHT:0in;BORDER-TOP:#b5c4df 1pt solid;BORDER-RIGHT:medium none;PADDING-TOP:3pt">
<span style="font-weight:bold">From: </span>Matt Kassawara <<a href="mailto:mkassawara@gmail.com" target="_blank">mkassawara@gmail.com</a>><br>
<span style="font-weight:bold">Date: </span>Thursday, June 12, 2014 11:43 AM<br>
<span style="font-weight:bold">To: </span>Anne Gentle <<a href="mailto:anne@openstack.org" target="_blank">anne@openstack.org</a>><br>
<span style="font-weight:bold">Cc: </span>Diane Fleming <<a href="mailto:diane.fleming@rackspace.com" target="_blank">diane.fleming@rackspace.com</a>>, "<a href="mailto:openstack-docs@lists.openstack.org" target="_blank">openstack-docs@lists.openstack.org</a>"
<<a href="mailto:openstack-docs@lists.openstack.org" target="_blank">openstack-docs@lists.openstack.org</a>><br>
<span style="font-weight:bold">Subject: </span>Re: [Openstack-docs] Installation and configuration section structure<br>
</div>
<div>
<div>
<div><br>
</div>
<div>
<div>
<div dir="ltr">Makes sense! However, I think services other than neutron need some restructuring (mostly reordering of steps) to improve flow. For example, the nova controller steps bounce around between prerequisites and editing configuration files. We should
first provide all of the prerequisites, then install packages and configure the service, and finally verify functionality (when applicable). I suspect much of this "jumbling" came as a side-effect of integrating tools such as openstack-config and openstack-db
with generic editing of configuration files. Removal of these tools should help us provide a consistent structure among services for all distributions. For the installation guide improvements project, we should evaluate the complexity of each service to determine
if multiple procedures improve the flow of installation/configuration. Keystone appears to work with one procedure for installation/configuration, so we'll run with it after I make some additional minor changes from comments in a similar patch.</div>
<div class="gmail_extra"><br>
<br>
<div class="gmail_quote">On Thu, Jun 12, 2014 at 10:16 AM, 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>On Thu, Jun 12, 2014 at 11:01 AM, Matt Kassawara <span dir="ltr"><<a href="mailto:mkassawara@gmail.com" target="_blank">mkassawara@gmail.com</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">Anyone else want to comment? This issue affects most of the installation guide improvement patches.</div>
<div>
<div>
<div class="gmail_extra"><br>
</div>
</div>
</div>
</blockquote>
<div><br>
</div>
</div>
<div>Yes of course. :)</div>
<div><br>
</div>
<div>The non-neutron portions of the guide are well-written and shouldn't really be revised much. They've been reviewed and tested for a long time and that simplicity should remain.</div>
<div><br>
</div>
<div>The neutron portions of the guide can be revised but they can be written differently due to the increasing complexity.</div>
<div><br>
</div>
<div>So I agree with Diane that strict consistency isn't required here, and is not a value-add. The services are quite different and the history of the guide sections warrants only revising the neutron procedures.</div>
<div><br>
</div>
<div>Anne </div>
<div><br>
</div>
<blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">
<div>
<div>
<div>
<div>
<div class="gmail_extra"><br>
<div class="gmail_quote">On Wed, Jun 11, 2014 at 1:33 PM, Diane Fleming <span dir="ltr">
<<a href="mailto:diane.fleming@rackspace.com" target="_blank">diane.fleming@rackspace.com</a>></span> wrote:<br>
<blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">
<div style="word-wrap:break-word;color:rgb(0,0,0);font-size:14px;font-family:Calibri,sans-serif">
<div>
<div>
<div>Thanks Matt.</div>
<div><br>
</div>
<div>I'm in favor of breaking procedures that are longer than 10 steps into smaller procedures. Otherwise, when possible, use a single procedure.</div>
<div><br>
</div>
<div>I don't think consistency gains us much, if anything, in this case. </div>
<div><br>
</div>
<div>Here's some good general guidance about procedures:</div>
<div><br>
</div>
<div><a href="http://www.helpscribe.com/2008/01/11-tips-for-writing-incredibly-useful.html" target="_blank">http://www.helpscribe.com/2008/01/11-tips-for-writing-incredibly-useful.html</a></div>
<div><br>
</div>
<div>
<div>
<div style="color:rgb(0,0,0)"><font color="rgb(0, 0, 0)" face="Apple Chancery"><i>Diane</i></font></div>
<div style="font-family:Calibri,sans-serif;font-size:14px;color:rgb(0,0,0)"><font color="rgb(0, 0, 0)"><i>----------------------------------------------</i></font></div>
<div style="font-family:Calibri,sans-serif;font-size:14px;color:rgb(0,0,0)"><font color="rgb(0, 0, 0)">Diane Fleming</font></div>
<div style="font-family:Calibri,sans-serif;font-size:14px">
<div style="color:rgb(0,0,0)">Software Developer II - US</div>
</div>
<a href="mailto:diane.fleming@rackspace.com" target="_blank">diane.fleming@rackspace.com</a></div>
<div>Cell <a href="tel:512.323.6799" value="+15123236799" target="_blank">512.323.6799</a></div>
<div>Office <a href="tel:512.874.1260" value="+15128741260" target="_blank">512.874.1260</a><br>
<div style="font-family:Calibri,sans-serif;font-size:14px">
<div style="color:rgb(0,0,0)">Skype drfleming0227</div>
<div style="color:rgb(0,0,0)">Google-plus <a href="mailto:diane.fleming@gmail.com" target="_blank">
diane.fleming@gmail.com</a></div>
</div>
</div>
</div>
</div>
</div>
<div><br>
</div>
<span>
<div style="font-family:Lucida Grande;font-size:11pt;text-align:left;color:black;BORDER-BOTTOM:medium none;BORDER-LEFT:medium none;PADDING-BOTTOM:0in;PADDING-LEFT:0in;PADDING-RIGHT:0in;BORDER-TOP:#b5c4df 1pt solid;BORDER-RIGHT:medium none;PADDING-TOP:3pt">
<span style="font-weight:bold">From: </span>Matt Kassawara <<a href="mailto:mkassawara@gmail.com" target="_blank">mkassawara@gmail.com</a>><br>
<span style="font-weight:bold">Date: </span>Wednesday, June 11, 2014 2:03 PM<br>
<span style="font-weight:bold">To: </span>"<a href="mailto:openstack-docs@lists.openstack.org" target="_blank">openstack-docs@lists.openstack.org</a>" <<a href="mailto:openstack-docs@lists.openstack.org" target="_blank">openstack-docs@lists.openstack.org</a>><br>
<span style="font-weight:bold">Subject: </span>[Openstack-docs] Installation and configuration section structure<br>
</div>
<div>
<div>
<div><br>
</div>
<div>
<div>
<div dir="ltr">
<div>Prior to the Icehouse installation guide networking updates project, the structure for most installation and configuration sections consisted of one procedure containing steps/substeps. While working on the networking updates project, I found this structure
difficult for us to code and for our audience to follow with more complex services such as neutron. After trying some variants of the original structure, I eventually decided to break each group of related steps into separate procedures. To provide our audience
with consistency, I think we should implement this structure throughout the installation guide during the improvement project. However, this structure leans toward overkill for simpler services such as keystone. We need to determine whether we stick with consistency
or adjust structure based on service complexity. Please take a look at the following examples of each structure and provide your opinions.</div>
<div><br>
</div>
<div>Separate procedures:</div>
<div><br>
</div>
<div><a href="http://docs.openstack.org/icehouse/install-guide/install/apt/content/neutron-ml2-network-node.html" target="_blank">http://docs.openstack.org/icehouse/install-guide/install/apt/content/neutron-ml2-network-node.html</a><br>
</div>
<div><br>
</div>
<div><a href="http://docs-draft.openstack.org/59/96059/4/check/gate-openstack-manuals-tox-doc-publish-checkbuild/32a4a38/publish-docs/trunk/install-guide/install/apt/content/keystone-install.html" target="_blank">http://docs-draft.openstack.org/59/96059/4/check/gate-openstack-manuals-tox-doc-publish-checkbuild/32a4a38/publish-docs/trunk/install-guide/install/apt/content/keystone-install.html</a><br>
</div>
<div><br>
</div>
<div>One procedure:</div>
<div><br>
</div>
<div><a href="http://docs-draft.openstack.org/59/96059/10/check/gate-openstack-manuals-tox-doc-publish-checkbuild/d804200/publish-docs/trunk/install-guide/install/apt/content/keystone-install.html" target="_blank">http://docs-draft.openstack.org/59/96059/10/check/gate-openstack-manuals-tox-doc-publish-checkbuild/d804200/publish-docs/trunk/install-guide/install/apt/content/keystone-install.html</a><br>
</div>
<div><br>
</div>
<div>Matt</div>
</div>
</div>
</div>
</div>
</div>
</span></div>
</blockquote>
</div>
<br>
</div>
</div>
</div>
<br>
</div>
</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>
</blockquote>
</div>
<br>
</div>
</div>
</blockquote>
</div>
<br>
</div>
</div>
</div>
</div>
</div>
</span></div>
</blockquote>
</div>
<br>
</div>
</div>
</div>
</div></div></span>
</div>
</blockquote></div><br></div>