<div dir="ltr">Agreed with Diane here, you want to keep the steps short and sweet. <div><br></div><div>I also think the convention should be to use a colon prior to the command. This helps us match up with Sphinx/RST conventions of ending with :: in order to markup a command line entry. </div>

<div><br></div><div>Your steps should start with a verb, an action for the user to follow, then after the colon make sure to put the correct prompt and markup.</div><div><br></div><div>Thanks for asking! Mo' consistency, mo' bettah.</div>

<div><br></div><div>Anne</div></div><div class="gmail_extra"><br><br><div class="gmail_quote">On Sat, Mar 8, 2014 at 10:17 PM, Diane Fleming <span dir="ltr"><<a href="mailto:diane.fleming@rackspace.com" target="_blank">diane.fleming@rackspace.com</a>></span> wrote:<br>

<blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">Matt,<br>
<br>
Based on your example, it seems like you're combining two types of information - conceptual and procedural. I think the best practice is to describe concepts before the procedure.  Also, place the results of commands after the commands. So each step in a procedure would start with a simple directive with a colon followed by the command, and possibly followed with a description of the results of the command.<br>


<br>
For example....<br>
<br>
Certain users have the admin role, which permits them to handle administrative tasks. To create an admin user, complete these steps.<br>
<br>
1. Create the admin user:<br>
    $ keystone xxxxx<br>
2. Assign the admin role to the user:<br>
    $ keystone xxxx<br>
The command blah blah.<br>
3. Xxxx<br>
<br>
<br>
Sent from my iPhone<br>
<div><div class="h5"><br>
> On Mar 8, 2014, at 8:42 PM, "Matt Kassawara" <<a href="mailto:mkassawara@gmail.com">mkassawara@gmail.com</a>> wrote:<br>
><br>
> 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:<br>


><br>
> 1) Create the "admin" user. The "admin" user handles administrative tasks:<br>
><br>
> > keystone user-create ...<br>
><br>
> We could rearrange the step to make the instruction follow the supporting sentences. For example:<br>
><br>
> 1) The "admin" user handles administrative tasks. Create the "admin" user:<br>
><br>
> > keystone user-create ...<br>
><br>
> However, this doesn't work in all situations... particularly steps containing a considerable number of supporting sentences.<br>
><br>
> Alternatively, we could simply end each sentence in a step with a period. For example:<br>
><br>
> 1) The "admin" user handles administrative tasks. Create the "admin" user.<br>
><br>
> > keystone user-create ...<br>
><br>
> Indentation of the command in the rendering seems to imply the colon without actually using it.<br>
><br>
> In some cases, using a colon makes sense. For example:<br>
><br>
> You would use a colon when providing an example within a paragraph.<br>
><br>
> (See what I did there?)<br>
><br>
> 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!<br>
</div></div>> _______________________________________________<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>
_______________________________________________<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>
</blockquote></div><br></div>