<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=Windows-1252">
</head>
<body dir="auto">
<div>I wouldn't worry about use of gerunds other than in titles. <br>
<br>
Sent from my iPhone</div>
<div><br>
On Jun 8, 2014, at 10:38 AM, "Matt Kassawara" <<a href="mailto:mkassawara@gmail.com">mkassawara@gmail.com</a>> wrote:<br>
<br>
</div>
<blockquote type="cite">
<div>
<div dir="ltr">Makes sense to me. The primary goal of these conventions helps us provide the target audience with consistent, succinct structure that minimizes confusion and improves translation.
<div>
<div>
<div><br>
</div>
<div>My thoughts...<br>
<div><br>
</div>
<div>1) Table/figure title</div>
<div> a) Use fragment to describe object (table/figure number automatically assigned)</div>
<div> Example: Three-node architecture with OpenStack Networking (neutron)</div>
<div><br>
</div>
<div>2) Table/figure reference</div>
</div>
<div> a) Use <xref linkend="table/figure" /> (or more customizable tag if necessary to change link text) with supporting structure around it.</div>
<div> Example: See Figure 1.2, “Three-node architecture with OpenStack Networking (neutron)” for more information.</div>
<div><br>
</div>
<div>3) Step</div>
<div> a) Provide primary instruction as sentence that ends with a colon. Provide supporting instructions after the command or configuration snippet as sentences that end with periods.</div>
<div> Example: Configure thinger:</div>
<div> [command or configuration snippet with replaceables ITEM_1 and ITEM_2]</div>
<div> Replace ITEM_1 with one thing and ITEM_2 with another thing.</div>
<div><br>
</div>
<div>4) Replacement values</div>
<div> a) Existing use of <replaceable>ITEM_1</replaceable> seems to work. Any other cases to consider?</div>
<div><br>
</div>
<div>5) Gerunds</div>
<div> a) The conventions page only mentions avoiding gerunds in headings. This issue tends to draw strong opinions for content, so I would like others to join the discussion. *raises shields*</div>
</div>
</div>
</div>
<div class="gmail_extra"><br>
<br>
<div class="gmail_quote">On Sun, Jun 8, 2014 at 8:35 AM, Diane Fleming <span dir="ltr">
<<a href="mailto:diane.fleming@rackspace.com" target="_blank">diane.fleming@rackspace.com</a>></span> wrote:<br>
<blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">
Matt,<br>
<br>
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:<br>
<br>
1. Style for introductory sentences. Introductory sentences introduce tables, lists, steps, figures, and so on. Always end an introductory sentence with a colon (:).<br>
Table example: This table describes the xxx parameters:<br>
Figure example: This figure shows the relationship between xx and xx:<br>
Step example: Configure the xx:<br>
Step example: To configure xxx, run this command and replace xx with xx:<br>
(These are not prescriptive - just giving some examples of what these conventions might be)<br>
2. Style for replacement values.<br>
3. Avoid use of gerunds. (there are lots of reasons for this - here are some: <a href="http://idratherbewriting.com/2008/02/11/are-gerunds-in-topic-titles-problematic-in-search-results/" target="_blank">
http://idratherbewriting.com/2008/02/11/are-gerunds-in-topic-titles-problematic-in-search-results/</a> and
<a href="http://ffeathers.wordpress.com/2013/10/12/death-of-the-gerund-in-technical-documentation/" target="_blank">
http://ffeathers.wordpress.com/2013/10/12/death-of-the-gerund-in-technical-documentation/</a> and
<a href="http://en.wikipedia.org/wiki/Simplified_Technical_English#Writing_Rules" target="_blank">
http://en.wikipedia.org/wiki/Simplified_Technical_English#Writing_Rules</a>)<br>
<br>
Diane<br>
________________________________________<br>
From: Matt Kassawara [<a href="mailto:mkassawara@gmail.com">mkassawara@gmail.com</a>]<br>
Sent: Saturday, June 07, 2014 7:46 PM<br>
To: Anne Gentle<br>
Cc: Diane Fleming; <a href="mailto:openstack-docs@lists.openstack.org">openstack-docs@lists.openstack.org</a><br>
Subject: Re: [Openstack-docs] Structure for steps with additional information<br>
<br>
Yep!<br>
<br>
<br>
On Sat, Jun 7, 2014 at 5:09 PM, Anne Gentle <<a href="mailto:anne@openstack.org">anne@openstack.org</a><mailto:<a href="mailto:anne@openstack.org">anne@openstack.org</a>>> wrote:<br>
<div class=""><br>
<br>
<br>
On Sat, Jun 7, 2014 at 5:49 PM, Diane Fleming <<a href="mailto:diane.fleming@rackspace.com">diane.fleming@rackspace.com</a><mailto:<a href="mailto:diane.fleming@rackspace.com">diane.fleming@rackspace.com</a>>> wrote:<br>
Well, you don't "configure by replacing" (which is what the sentence suggests). The main point/action of the step is configuration.<br>
<br>
Maybe:<br>
<br>
Configure xx in the xx section. In the command, replace xx with xx.<br>
<br>
<command><br>
<br>
Honestly, I don't think we should get too hung up on colons versus periods.<br>
<br>
<br>
<br>
Sent from my iPhone<br>
<br>
</div>
<div class="">On Jun 7, 2014, at 4:50 PM, "Matt Kassawara" <<a href="mailto:mkassawara@gmail.com">mkassawara@gmail.com</a><mailto:<a href="mailto:mkassawara@gmail.com">mkassawara@gmail.com</a>>> wrote:<br>
<br>
Anne,<br>
<br>
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.<br>
<br>
Matt<br>
<br>
P.S. - I'm curious how Diane feels about the gerund. :)<br>
<br>
<br>
</div>
On Sat, Jun 7, 2014 at 12:31 PM, Anne Gentle <<a href="mailto:anne@openstack.org">anne@openstack.org</a><mailto:<a href="mailto:anne@openstack.org">anne@openstack.org</a>>> wrote:<br>
<div>
<div class="h5"><br>
<br>
<br>
On Fri, Jun 6, 2014 at 10:06 PM, Matt Kassawara <<a href="mailto:mkassawara@gmail.com">mkassawara@gmail.com</a><mailto:<a href="mailto:mkassawara@gmail.com">mkassawara@gmail.com</a>>> wrote:<br>
We should discuss and agree on the structure for steps that include additional information, typically sentences that reference replaceables.<br>
<br>
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?<br>
<br>
<br>
For example:<br>
<br>
1) Configure database access in the [database] section:<br>
<br>
Replace HEAT_DBPASS with the password you chose for the Orchestration database.<br>
<br>
[database]<br>
...<br>
connection = mysql://heat:HEAT_DBPASS@controller/heat<br>
<br>
<br>
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:<br>
<br>
Configure database access in the [database] section by replacing HEAT_DBPASS with the Orchestration database password:<br>
<br>
[database]<br>
...<br>
<br>
<br>
<br>
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.<br>
<br>
Potential alternatives:<br>
<br>
1) Configure database access in the [database] section. Replace HEAT_DBPASS with the password you chose for the Orchestration database:<br>
<br>
[database]<br>
...<br>
connection = mysql://heat:HEAT_DBPASS@controller/heat<br>
<br>
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.<br>
<br>
1) Configure database access in the [database] section:<br>
<br>
Note: Replace HEAT_DBPASS with the password you chose for the Orchestration database.<br>
<br>
[database]<br>
...<br>
connection = mysql://heat:HEAT_DBPASS@controller/heat<br>
<br>
Additional sentences use the "note" admonition. I seem to recall some -1's for this variant primarily because admonitions take up too much space.<br>
<br>
1) Configure database access in the [database] section and replace HEAT_DBPASS with the password you chose for the Orchestration database:<br>
<br>
[database]<br>
...<br>
connection = mysql://heat:HEAT_DBPASS@controller/heat<br>
<br>
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.<br>
<br>
For example:<br>
<br>
1) Create Identity service credentials:<br>
<br>
a) Create the heat user and replace HEAT_PASS with a suitable password and EMAIL_ADDRESS with a suitable e-mail address.<br>
<br>
$ keystone user-create --name heat --pass HEAT_PASS --email<br>
EMAIL_ADDRESS<br>
<br>
What shall we do?<br>
<br>
Matt<br>
<br>
_______________________________________________<br>
Openstack-docs mailing list<br>
</div>
</div>
<a href="mailto:Openstack-docs@lists.openstack.org">Openstack-docs@lists.openstack.org</a><mailto:<a href="mailto:Openstack-docs@lists.openstack.org">Openstack-docs@lists.openstack.org</a>><br>
<div class=""><a href="http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs" target="_blank">http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs</a><br>
<br>
<br>
<br>
_______________________________________________<br>
Openstack-docs mailing list<br>
</div>
<a href="mailto:Openstack-docs@lists.openstack.org">Openstack-docs@lists.openstack.org</a><mailto:<a href="mailto:Openstack-docs@lists.openstack.org">Openstack-docs@lists.openstack.org</a>><br>
<a href="http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs" target="_blank">http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs</a><br>
<br>
<br>
</blockquote>
</div>
<br>
</div>
</div>
</blockquote>
</body>
</html>