Open Stack

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

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
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20140606/98a5a0ea/attachment.html>