<div dir="ltr">I am seeking some clarification on use of colons in the documentation. While using the colon often makes sense for steps involving a single sentence, it doesn't seem to make sense when the supporting sentences follow the instruction. For example:<div>
<div><div><br></div><div>1) Create the "admin" user. The "admin" user handles administrative tasks:</div><div><br></div><div>> keystone user-create ...</div><div><br></div><div>We could rearrange the step to make the instruction follow the supporting sentences. For example:</div>
<div><br></div><div>1) The "admin" user handles administrative tasks. Create the "admin" user:</div><div><br></div><div>> keystone user-create ...</div><div><br></div><div>However, this doesn't work in all situations... particularly steps containing a considerable number of supporting sentences.</div>
<div><br></div><div>Alternatively, we could simply end each sentence in a step with a period. For example:</div><div><br></div><div>1) The "admin" user handles administrative tasks. Create the "admin" user.</div>
<div><br></div><div>> keystone user-create ...</div><div><br></div><div>Indentation of the command in the rendering seems to imply the colon without actually using it.</div><div><br></div><div>In some cases, using a colon makes sense. For example:</div>
<div><br></div><div>You would use a colon when providing an example within a paragraph.</div><div><br></div><div>(See what I did there?)</div><div><br></div><div>For consistency, I would like to stick with one way or another... preferably avoiding the colon outside of referencing examples within a paragraph. Getting us all on the same page reduces review cycles!</div>
</div></div></div>