Open Stack

Yep!


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

>
>
>
> 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/f4fc1536/attachment-0001.html>