Open Stack

Matt, 

I think there are a few issues you're trying to address here, and I think each one requires its own guidance on the conventions page:

1. Style for introductory sentences. Introductory sentences introduce tables, lists, steps, figures, and so on. Always end an introductory sentence with a colon (:).
    Table example: This table describes the xxx parameters: 
    Figure example: This figure shows the relationship between xx and xx:
    Step example: Configure the xx:
    Step example: To configure xxx, run this command and replace xx with xx:
    (These are not prescriptive - just giving some examples of what these conventions might be)
2. Style for replacement values. 
3. Avoid use of gerunds. (there are lots of reasons for this - here are some: http://idratherbewriting.com/2008/02/11/are-gerunds-in-topic-titles-problematic-in-search-results/ and http://ffeathers.wordpress.com/2013/10/12/death-of-the-gerund-in-technical-documentation/ and http://en.wikipedia.org/wiki/Simplified_Technical_English#Writing_Rules)

Diane
________________________________________
From: Matt Kassawara [mkassawara at gmail.com]
Sent: Saturday, June 07, 2014 7:46 PM
To: Anne Gentle
Cc: Diane Fleming; openstack-docs at lists.openstack.org
Subject: Re: [Openstack-docs] Structure for steps with additional information

Yep!


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



On Sat, Jun 7, 2014 at 5:49 PM, Diane Fleming <diane.fleming at rackspace.com<mailto: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<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.

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<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