<div dir="ltr"> <div class="gmail_extra"><br><br><div class="gmail_quote">On Fri, Jun 6, 2014 at 10:06 PM, 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">We should discuss and agree on the structure for steps that include additional information, typically sentences that reference replaceables.<div>

<br></div><div>For example:<div><br></div><div><div>1) Configure database access in the [database] section:</div>
<div><br></div><div>Replace HEAT_DBPASS with the password you chose for the Orchestration database.</div><div><br></div><div>[database]</div><div>...</div><div>connection = mysql://heat:HEAT_DBPASS@controller/heat</div><div>


<br></div></div></div></div></blockquote><div><br></div><div>This one works but could be shorter/cleaner. My only concern is that the primary instruction is "configure" but the action is "replace" -- why not have this:</div>

<div><br></div><div>Configure database access in the [database] section by replacing HEAT_DBPASS with the Orchestration database password:</div><div><br></div><div>[database]</div><div>...</div><div><br></div><div><br></div>

<div> </div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex"><div dir="ltr"><div><div><div></div><div>The primary instruction ends with a colon and additional sentences end with a period. The networking content approved for Icehouse and some patches for the installation guide improvement project use this structure.</div>


</div><div><br></div><div>Potential alternatives:</div><div><br></div><div><div>1) Configure database access in the [database] section. Replace HEAT_DBPASS with the password you chose for the Orchestration database:</div>


<div><br></div><div>[database]</div><div>...</div><div>connection = mysql://heat:HEAT_DBPASS@controller/heat</div></div><div><br></div><div>The primary instruction and additional sentences use the same paragraph. The last sentence ends with a colon. The location of the colon could obfuscate the primary instruction.</div>


<div><br></div><div><div>1) Configure database access in the [database] section:</div><div><br></div><div>Note: Replace HEAT_DBPASS with the password you chose for the Orchestration database.</div><div><br></div><div>[database]</div>


<div>...</div><div>connection = mysql://heat:HEAT_DBPASS@controller/heat</div></div></div><div><br></div><div>Additional sentences use the "note" admonition. I seem to recall some -1's for this variant primarily because admonitions take up too much space.</div>


<div><br></div><div><div>1) Configure database access in the [database] section and replace HEAT_DBPASS with the password you chose for the Orchestration database:</div><div><br></div><div>[database]</div><div>...</div><div>


connection = mysql://heat:HEAT_DBPASS@controller/heat</div></div><div><br></div><div>Join the primary instruction and additional sentences to form one sentence. While this works for steps with one additional sentence, those with multiple additional sentences become wordy and awkward.</div>


<div><br></div><div>For example:</div><div><br></div><div><div>1) Create Identity service credentials:</div><div><br></div><div>    a) Create the heat user and replace HEAT_PASS with a suitable password and         EMAIL_ADDRESS with a suitable e-mail address.</div>


<div><br></div><div>        $ keystone user-create --name heat --pass HEAT_PASS --email</div><div>        EMAIL_ADDRESS</div></div><div><br></div><div>What shall we do?</div><span class="HOEnZb"><font color="#888888"><div>

<br></div><div>Matt</div></font></span></div>
<br>_______________________________________________<br>
Openstack-docs mailing list<br>
<a href="mailto:Openstack-docs@lists.openstack.org">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>