Open Stack

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<mailto: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<mailto:anne at openstack.org>> wrote:



On Fri, Jun 6, 2014 at 10:06 PM, Matt Kassawara <mkassawara at gmail.com<mailto: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<mailto: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<mailto: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/8a3b0778/attachment-0001.html>