Open Stack

Agreed with Diane here, you want to keep the steps short and sweet.

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.

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.

Thanks for asking! Mo' consistency, mo' bettah.

Anne


On Sat, Mar 8, 2014 at 10:17 PM, Diane Fleming
<diane.fleming at rackspace.com>wrote:

> 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
>
> _______________________________________________
> Openstack-docs mailing list
> Openstack-docs at lists.openstack.org
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20140309/fa0f2610/attachment.html>