<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=us-ascii">
</head>
<body style="word-wrap: break-word; -webkit-nbsp-mode: space; -webkit-line-break: after-white-space; 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">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 class="Apple-style-span" 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 class="Apple-style-span" 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 class="Apple-style-span" 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>
diane.fleming@rackspace.com</div>
<div>Cell 512.323.6799</div>
<div>Office 512.874.1260<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 diane.fleming@gmail.com</div>
</div>
</div>
</div>
</div>
</div>
<div><br>
</div>
<span id="OLK_SRC_BODY_SECTION">
<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">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">openstack-docs@lists.openstack.org</a>" <<a href="mailto:openstack-docs@lists.openstack.org">openstack-docs@lists.openstack.org</a>><br>
<span style="font-weight:bold">Subject: </span>[Openstack-docs] Installation and configuration section structure<br>
</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">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">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">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>
</span>
</body>
</html>