Open Stack

I think #1. With the example between the intro text and the extra information. No need for note tag.  Like this:

Configure the thingamabob:

$ abc REPLACE-ME

Replace REPLACE-ME with something more original.




Sent from my iPhone

> On Jun 6, 2014, at 10:08 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
> 
> 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