Open Stack

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
# 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> 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> 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/e3a2ddb4/attachment.html>