<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=us-ascii">
</head>
<body dir="auto">
<div>Well, you don't "configure by replacing" (which is what the sentence suggests). The main point/action of the step is configuration. </div>
<div><br>
</div>
<div>Maybe: </div>
<div><br>
</div>
<div>Configure xx in the xx section. In the command, replace xx with xx.</div>
<div><br>
</div>
<div><command></div>
<div><br>
</div>
<div>Honestly, I don't think we should get too hung up on colons versus periods. </div>
<div><br>
</div>
<div><br>
<br>
Sent from my iPhone</div>
<div><br>
On Jun 7, 2014, at 4:50 PM, "Matt Kassawara" <<a href="mailto:mkassawara@gmail.com">mkassawara@gmail.com</a>> wrote:<br>
<br>
</div>
<blockquote type="cite">
<div>
<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>
</div>
</blockquote>
<blockquote type="cite">
<div><span>_______________________________________________</span><br>
<span>Openstack-docs mailing list</span><br>
<span><a href="mailto:Openstack-docs@lists.openstack.org">Openstack-docs@lists.openstack.org</a></span><br>
<span><a href="http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs">http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs</a></span><br>
</div>
</blockquote>
</body>
</html>