<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>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><div><br></div><div>Matt</div></div>