Open Stack

Anne,

I think the replacement action functions as a dependency of the primary
configuration instruction. In your example, the primary configuration
instruction references the "keystone user-create" command, but requires
replacement of HEAT_PASS and EMAIL_ADDRESS with suitable strings to
complete it. However, your suggestion seems to resolve the issue of
sentence consolidation awkwardness for steps that reference more than one
replaceable.

Matt

P.S. - I'm curious how Diane feels about the gerund. :)


On Sat, Jun 7, 2014 at 12:31 PM, Anne Gentle <anne at openstack.org> wrote:

>
>
>
> On Fri, Jun 6, 2014 at 10:06 PM, Matt Kassawara <mkassawara at gmail.com>
> wrote:
>
>> We should discuss and agree on the structure for steps that include
>> additional information, typically sentences that reference replaceables.
>>
>> For example:
>>
>> 1) Configure database access in the [database] section:
>>
>> Replace HEAT_DBPASS with the password you chose for the Orchestration
>> database.
>>
>> [database]
>> ...
>> connection = mysql://heat:HEAT_DBPASS@controller/heat
>>
>>
> This one works but could be shorter/cleaner. My only concern is that the
> primary instruction is "configure" but the action is "replace" -- why not
> have this:
>
> Configure database access in the [database] section by replacing
> HEAT_DBPASS with the Orchestration database password:
>
> [database]
> ...
>
>
>
>
>> The primary instruction ends with a colon and additional sentences end
>> with a period. The networking content approved for Icehouse and some
>> patches for the installation guide improvement project use this structure.
>>
>> Potential alternatives:
>>
>> 1) Configure database access in the [database] section. Replace
>> HEAT_DBPASS with the password you chose for the Orchestration database:
>>
>> [database]
>> ...
>> connection = mysql://heat:HEAT_DBPASS@controller/heat
>>
>> The primary instruction and additional sentences use the same paragraph.
>> The last sentence ends with a colon. The location of the colon could
>> obfuscate the primary instruction.
>>
>> 1) Configure database access in the [database] section:
>>
>> Note: Replace HEAT_DBPASS with the password you chose for the
>> Orchestration database.
>>
>> [database]
>> ...
>> connection = mysql://heat:HEAT_DBPASS@controller/heat
>>
>> Additional sentences use the "note" admonition. I seem to recall some
>> -1's for this variant primarily because admonitions take up too much space.
>>
>> 1) Configure database access in the [database] section and replace
>> HEAT_DBPASS with the password you chose for the Orchestration database:
>>
>> [database]
>> ...
>> connection = mysql://heat:HEAT_DBPASS@controller/heat
>>
>> Join the primary instruction and additional sentences to form one
>> sentence. While this works for steps with one additional sentence, those
>> with multiple additional sentences become wordy and awkward.
>>
>> For example:
>>
>> 1) Create Identity service credentials:
>>
>>     a) Create the heat user and replace HEAT_PASS with a suitable
>> password and         EMAIL_ADDRESS with a suitable e-mail address.
>>
>>         $ keystone user-create --name heat --pass HEAT_PASS --email
>>         EMAIL_ADDRESS
>>
>> What shall we do?
>>
>> Matt
>>
>> _______________________________________________
>> 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/20140607/73442ef7/attachment.html>