<div dir="ltr">Ahhh, now this makes sense to me. I'll try to stick with this convention for the Icehouse Networking updates and address existing issues elsewhere as necessary. Sorry for the confusion!</div><div class="gmail_extra">
<br><br><div class="gmail_quote">On Sun, Mar 9, 2014 at 9:56 AM, 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">




<div style="font-size:14px;font-family:Calibri,sans-serif;word-wrap:break-word">
<div>
<div>
<div>
<div>Hey Matt, </div>
<div><br>
</div>
<div>I still think there's a mix of concepts and tasks in the procedure. </div>
<div><br>
</div>
<div>If you pull all the concepts to an overview before the procedure, then the procedure can be short and sweet, with very little explanation.</div>
<div><br>
</div>
<div>In dita, it's recommended that any procedure longer than 10 steps be broken into multiple procedures. It's also okay to create sub steps in a procedure:</div>
<div><br>
</div>
<div>
<p style="margin:0.0px 0.0px 0.0px 0.0px;font:12.0px Helvetica"><span style="color:#0e22a0"><procedure><title></span>To open the door<span style="color:#0e22a0"></title></span><br>
                <span style="color:#0e22a0"><step><para></span>Grab the door knob.<span style="color:#0e22a0"></para></step></span><br>
                <span style="color:#0e22a0"><step><para></span>Turn the door knob to the left.<span style="color:#0e22a0"></para></span><br>
                <span style="color:#0e22a0"><substeps></span><br>
                    <span style="color:#0e22a0"><step><para></span>Make sure the dog is secure.<span style="color:#0e22a0"></para></step></span><br>
                    <span style="color:#0e22a0"><step><para></span>Make sure the cat is secure.<span style="color:#0e22a0"></para></step></span><br>
                <span style="color:#0e22a0"></substeps></step></span><br>
            <span style="color:#0e22a0"></procedure></span></p>
</div>
<div><br>
</div>
<div>Anyway, here's a suggested rewrite of your "situation" steps:</div>
<div><br>
</div>
<div>Situation 1:</div>
<div><br>
</div>
<div>In intro before the procedure:</div><div class="">
<div><br>
</div>
<div>Compute stores information in a database. In this guide, we use a MySQL database on the controller node. </div>
</div><div>Compute uses a nova user to authenticate with the Identity Service.</div><div class="">
<div>You must register Compute with the Identity Service so that other OpenStack services can locate it. </div>
<div><br>
</div>
</div><div>procedure -></div>
<div><br>
</div>
<div>Step X. Configure the database location and credentials, where NOVA_DBPASS is the database password that you will create in a later step:<br>
</div><div class="">
<div><br>
</div>
<div>
<div># openstack-config --set /etc/nova/nova.conf \</div>
<div>  database connection mysql://nova:NOVA_DBPASS@controller/nova</div>
</div>
<div><br>
</div>
</div><div>
<div>Step Y: Create the nova user:</div>
<div><br>
</div>
<div><div class="">
<div># keystone user-create --name=nova --pass=NOVA_PASS --email=<a href="mailto:nova@example.com" target="_blank">nova@example.com</a></div>
<div><br>
</div>
</div><div>Step Z:  Give the nova user the admin role in the service tenant:</div><div class="">
<div><br>
</div>
<div># keystone user-role-add --user=nova --tenant=service --role=admin</div>
</div></div>
</div>
</div>
<div><br>
</div>
<div>
<div>Step ZZ: Register the Compute service and define its endpoint:<br>
</div><div class="">
<div><br>
</div>
<div>
<div># keystone service-create --name=nova --type=compute \</div>
<div>  --description="OpenStack Compute"</div>
<div># keystone endpoint-create \</div>
<div>  --service-id=$(keystone service-list | awk '/ compute / {print $2}') \</div>
<div>  --publicurl=<a href="http://controller:8774/v2/%\(tenant_id\)s" target="_blank">http://controller:8774/v2/%\(tenant_id\)s</a> \</div>
<div>  --internalurl=<a href="http://controller:8774/v2/%\(tenant_id\)s" target="_blank">http://controller:8774/v2/%\(tenant_id\)s</a> \</div>
<div>  --adminurl=<a href="http://controller:8774/v2/%\(tenant_id\)s" target="_blank">http://controller:8774/v2/%\(tenant_id\)s</a></div>
</div>
</div></div>
<div><br>
</div>
<div>
<div>
<div style><font color="rgb(0, 0, 0)" face="Apple Chancery"><i>Diane</i></font></div>
<div style="font-size:14px;font-family:Calibri,sans-serif">
<font color="rgb(0, 0, 0)"><i>----------------------------------------------</i></font></div>
<div style="font-size:14px;font-family:Calibri,sans-serif">
<font color="rgb(0, 0, 0)">Diane Fleming</font></div>
<div style="font-family:Calibri,sans-serif;font-size:14px">
<div style>Software Developer II - US</div>
</div>
<a href="mailto:diane.fleming@rackspace.com" target="_blank">diane.fleming@rackspace.com</a></div>
<div>Cell  <a href="tel:512.323.6799" value="+15123236799" target="_blank">512.323.6799</a></div>
<div>Office <a href="tel:512.874.1260" value="+15128741260" target="_blank">512.874.1260</a><br>
<div style="font-family:Calibri,sans-serif;font-size:14px">
<div style>Skype drfleming0227</div>
<div style>Google-plus <a href="mailto:diane.fleming@gmail.com" target="_blank">diane.fleming@gmail.com</a></div>
</div>
</div>
</div>
</div>
</div>
<div><br>
</div>
<span>
<div style="border-right:medium none;padding-right:0in;padding-left:0in;padding-top:3pt;text-align:left;font-size:11pt;border-bottom:medium none;font-family:Calibri;border-top:#b5c4df 1pt solid;padding-bottom:0in;border-left:medium none">

<span style="font-weight:bold">From: </span>Matt Kassawara <<a href="mailto:mkassawara@gmail.com" target="_blank">mkassawara@gmail.com</a>><br>
<span style="font-weight:bold">Date: </span>Sunday, March 9, 2014 10:44 AM<br>
<span style="font-weight:bold">To: </span>Anne Gentle <<a href="mailto:anne@openstack.org" target="_blank">anne@openstack.org</a>><br>
<span style="font-weight:bold">Cc: </span>Diane Fleming <<a href="mailto:diane.fleming@rackspace.com" target="_blank">diane.fleming@rackspace.com</a>>, "<a href="mailto:openstack-docs@lists.openstack.org" target="_blank">openstack-docs@lists.openstack.org</a>" <<a href="mailto:openstack-docs@lists.openstack.org" target="_blank">openstack-docs@lists.openstack.org</a>><br>

<span style="font-weight:bold">Subject: </span>Re: [Openstack-docs] Colon conventions<br>
</div><div><div class="h5">
<div><br>
</div>
<div>
<div>
<div dir="ltr">How about these situations?
<div><br>
</div>
<div>Situation 1:</div>
<div><br>
</div>
<div>Step X. Compute stores information in a database. In this guide, we use a MySQL database on the controller node. Configure Compute with the database location and credentials. Replace NOVA_DBPASS with the password for the database that you will create in
 a later step.<br>
</div>
<div><br>
</div>
<div>
<div># openstack-config --set /etc/nova/nova.conf \</div>
<div>  database connection mysql://nova:NOVA_DBPASS@controller/nova</div>
</div>
<div><br>
</div>
<div>I think the colon should appear after "Configure Compute with...", but wouldn't make sense for that sentence to appear after "Replace NOVA_DBPASS...". Alternatively, simply using periods with the existing order seems to work.</div>

<div><br>
</div>
<div>Situation 2:</div>
<div><br>
</div>
<div>Step Y: Create a nova user that Compute uses to authenticate with the Identity Service. Use the service tenant and give the user the admin role:</div>
<div><br>
</div>
<div>
<div># keystone user-create --name=nova --pass=NOVA_PASS --email=<a href="mailto:nova@example.com" target="_blank">nova@example.com</a></div>
<div># keystone user-role-add --user=nova --tenant=service --role=admin</div>
</div>
<div><br>
</div>
<div>Perhaps we should split this into two steps?</div>
<div><br>
</div>
<div>Situation 3:</div>
<div><br>
</div>
<div>Step Z: You must register Compute with the Identity Service so that other OpenStack services can locate it. Register the service and specify the endpoint:<br>
</div>
<div><br>
</div>
<div>
<div># keystone service-create --name=nova --type=compute \</div>
<div>  --description="OpenStack Compute"</div>
<div># keystone endpoint-create \</div>
<div>  --service-id=$(keystone service-list | awk '/ compute / {print $2}') \</div>
<div>  --publicurl=<a href="http://controller:8774/v2/%\(tenant_id\)s" target="_blank">http://controller:8774/v2/%\(tenant_id\)s</a> \</div>
<div>  --internalurl=<a href="http://controller:8774/v2/%\(tenant_id\)s" target="_blank">http://controller:8774/v2/%\(tenant_id\)s</a> \</div>
<div>  --adminurl=<a href="http://controller:8774/v2/%\(tenant_id\)s" target="_blank">http://controller:8774/v2/%\(tenant_id\)s</a></div>
</div>
<div><br>
</div>
<div>This makes sense to me since we provide the supporting sentence before the instruction and the latter flows well even with multiple commands.</div>
</div>
<div class="gmail_extra"><br>
<br>
<div class="gmail_quote">On Sun, Mar 9, 2014 at 9:10 AM, Anne Gentle <span dir="ltr">
<<a href="mailto:anne@openstack.org" target="_blank">anne@openstack.org</a>></span> wrote:<br>
<blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">
<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>
<span><font color="#888888">
<div><br>
</div>
<div>Anne</div>
</font></span></div>
<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><br>
> On Mar 8, 2014, at 8:42 PM, "Matt Kassawara" <<a href="mailto:mkassawara@gmail.com" target="_blank">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" target="_blank">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" target="_blank">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>
</div>
</div>
</blockquote>
</div>
<br>
</div>
</div>
</div>
</div></div></span>
</div>

</blockquote></div><br></div>