Open Stack

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!


On Sun, Mar 9, 2014 at 9:56 AM, Diane Fleming
<diane.fleming at rackspace.com>wrote:

>   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
>
>  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>
> Date: Sunday, March 9, 2014 10:44 AM
> To: Anne Gentle <anne at openstack.org>
> Cc: Diane Fleming <diane.fleming at rackspace.com>, "
> openstack-docs at lists.openstack.org" <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
> # 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/df1fb195/attachment.html>