Open Stack

On Sat, Jun 7, 2014 at 5:49 PM, Diane Fleming <diane.fleming at rackspace.com>
wrote:

>  Well, you don't "configure by replacing" (which is what the sentence
> suggests). The main point/action of the step is configuration.
>
>  Maybe:
>
>  Configure xx in the xx section. In the command, replace xx with xx.
>
>  <command>
>
>  Honestly, I don't think we should get too hung up on colons versus
> periods.
>
>
>
> Sent from my iPhone
>
> On Jun 7, 2014, at 4:50 PM, "Matt Kassawara" <mkassawara at gmail.com> wrote:
>
>   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.
>>>
>>
Okay let me make sure I understand the concern. You're trying to make sure
people know about replaceables no matter what the step's action is?


>
>>>  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
>>>
>>>
>>
>   _______________________________________________
> 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/5759ad42/attachment.html>