Open Stack

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.

My thoughts...

1) Table/figure title
    a) Use fragment to describe object (table/figure number automatically
assigned)
        Example: Three-node architecture with OpenStack Networking (neutron)

2) Table/figure reference
    a) Use <xref linkend="table/figure" /> (or more customizable tag if
necessary to change link text) with supporting structure around it.
        Example: See Figure 1.2, “Three-node architecture with OpenStack
Networking (neutron)” for more information.

3) Step
    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.
        Example: Configure thinger:
        [command or configuration snippet with replaceables ITEM_1 and
ITEM_2]
        Replace ITEM_1 with one thing and ITEM_2 with another thing.

4) Replacement values
    a) Existing use of <replaceable>ITEM_1</replaceable> seems to work. Any
other cases to consider?

5) Gerunds
    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*


On Sun, Jun 8, 2014 at 8:35 AM, Diane Fleming <diane.fleming at rackspace.com>
wrote:

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