Open Stack

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!
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20140308/49592bb5/attachment.html>