<div dir="ltr"><div>Anne,</div><div><br></div><div>I think the replacement action functions as a dependency of the primary configuration instruction. In your example, the primary configuration instruction references the "keystone user-create" command, but requires replacement of HEAT_PASS and EMAIL_ADDRESS with suitable strings to complete it. However, your suggestion seems to resolve the issue of sentence consolidation awkwardness for steps that reference more than one replaceable.</div>
<div><br></div><div>Matt</div><div><br></div><div>P.S. - I'm curious how Diane feels about the gerund. :)</div></div><div class="gmail_extra"><br><br><div class="gmail_quote">On Sat, Jun 7, 2014 at 12:31 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"> <div class="gmail_extra"><br><br><div class="gmail_quote"><div class="">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><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><div class="h5"><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><font color="#888888"><div>
<br></div><div>Matt</div></font></span></div>
<br></div></div><div class="">_______________________________________________<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></blockquote></div><br></div></div>
</blockquote></div><br></div>