Open Stack

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