Open Stack

Matt, 

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. 

For example....

Certain users have the admin role, which permits them to handle administrative tasks. To create an admin user, complete these steps. 

1. Create the admin user:
    $ keystone xxxxx
2. Assign the admin role to the user:
    $ keystone xxxx
The command blah blah.
3. Xxxx


Sent from my iPhone

> On Mar 8, 2014, at 8:42 PM, "Matt Kassawara" <mkassawara at gmail.com> wrote:
> 
> 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:
> 
> 1) Create the "admin" user. The "admin" user handles administrative tasks:
> 
> > keystone user-create ...
> 
> We could rearrange the step to make the instruction follow the supporting sentences. For example:
> 
> 1) The "admin" user handles administrative tasks. Create the "admin" user:
> 
> > keystone user-create ...
> 
> However, this doesn't work in all situations... particularly steps containing a considerable number of supporting sentences.
> 
> Alternatively, we could simply end each sentence in a step with a period. For example:
> 
> 1) The "admin" user handles administrative tasks. Create the "admin" user.
> 
> > keystone user-create ...
> 
> Indentation of the command in the rendering seems to imply the colon without actually using it.
> 
> In some cases, using a colon makes sense. For example:
> 
> You would use a colon when providing an example within a paragraph.
> 
> (See what I did there?)
> 
> 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!
> _______________________________________________
> Openstack-docs mailing list
> Openstack-docs at lists.openstack.org
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs