Open Stack

Hey Matt,

I still think there's a mix of concepts and tasks in the procedure.

If you pull all the concepts to an overview before the procedure, then the procedure can be short and sweet, with very little explanation.

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:


<procedure><title>To open the door</title>
                <step><para>Grab the door knob.</para></step>
                <step><para>Turn the door knob to the left.</para>
                <substeps>
                    <step><para>Make sure the dog is secure.</para></step>
                    <step><para>Make sure the cat is secure.</para></step>
                </substeps></step>
            </procedure>

Anyway, here's a suggested rewrite of your "situation" steps:

Situation 1:

In intro before the procedure:

Compute stores information in a database. In this guide, we use a MySQL database on the controller node.
Compute uses a nova user to authenticate with the Identity Service.
You must register Compute with the Identity Service so that other OpenStack services can locate it.

procedure ->

Step X. Configure the database location and credentials, where NOVA_DBPASS is the database password that you will create in a later step:

# openstack-config --set /etc/nova/nova.conf \
  database connection mysql://nova:NOVA_DBPASS@controller/nova

Step Y: Create the nova user:

# keystone user-create --name=nova --pass=NOVA_PASS --email=nova at example.com<mailto:nova at example.com>

Step Z:  Give the nova user the admin role in the service tenant:

# keystone user-role-add --user=nova --tenant=service --role=admin

Step ZZ: Register the Compute service and define its endpoint:

# keystone service-create --name=nova --type=compute \
  --description="OpenStack Compute"
# keystone endpoint-create \
  --service-id=$(keystone service-list | awk '/ compute / {print $2}') \
  --publicurl=http://controller:8774/v2/%\(tenant_id\)s \
  --internalurl=http://controller:8774/v2/%\(tenant_id\)s \
  --adminurl=http://controller:8774/v2/%\(tenant_id\)s

Diane
----------------------------------------------
Diane Fleming
Software Developer II - US
diane.fleming at rackspace.com
Cell  512.323.6799
Office 512.874.1260
Skype drfleming0227
Google-plus diane.fleming at gmail.com

From: Matt Kassawara <mkassawara at gmail.com<mailto:mkassawara at gmail.com>>
Date: Sunday, March 9, 2014 10:44 AM
To: Anne Gentle <anne at openstack.org<mailto:anne at openstack.org>>
Cc: Diane Fleming <diane.fleming at rackspace.com<mailto:diane.fleming at rackspace.com>>, "openstack-docs at lists.openstack.org<mailto:openstack-docs at lists.openstack.org>" <openstack-docs at lists.openstack.org<mailto:openstack-docs at lists.openstack.org>>
Subject: Re: [Openstack-docs] Colon conventions

How about these situations?

Situation 1:

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.

# openstack-config --set /etc/nova/nova.conf \
  database connection mysql://nova:NOVA_DBPASS@controller/nova

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.

Situation 2:

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:

# keystone user-create --name=nova --pass=NOVA_PASS --email=nova at example.com<mailto:nova at example.com>
# keystone user-role-add --user=nova --tenant=service --role=admin

Perhaps we should split this into two steps?

Situation 3:

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:

# keystone service-create --name=nova --type=compute \
  --description="OpenStack Compute"
# keystone endpoint-create \
  --service-id=$(keystone service-list | awk '/ compute / {print $2}') \
  --publicurl=http://controller:8774/v2/%\(tenant_id\)s \
  --internalurl=http://controller:8774/v2/%\(tenant_id\)s \
  --adminurl=http://controller:8774/v2/%\(tenant_id\)s

This makes sense to me since we provide the supporting sentence before the instruction and the latter flows well even with multiple commands.


On Sun, Mar 9, 2014 at 9:10 AM, Anne Gentle <anne at openstack.org<mailto:anne at openstack.org>> wrote:
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<mailto: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<mailto: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<mailto: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<mailto: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/eb452097/attachment-0001.html>