Jump to: navigation, search

Documentation/Conventions

< Documentation
Revision as of 07:54, 27 July 2014 by Jaegerandi (talk | contribs) (WADL markup conventions)

Writing style

Use active voice

In general, write in active voice rather than passive voice.

  • Active voice identifies the agent of action as the subject of the verb—usually the user.
  • Passive voice identifies the recipient (not the source) of the action as the subject of the verb.

Active-voice sentences clarify the performer of an action and are easier to understand than passive-voice sentences. Passive voice is usually less engaging and more complicated than active voice. When you use passive voice, the actions and responses of the software can be difficult to distinguish from those of the user. In addition, passive voice usually requires more words than active voice.

Example correct usage:

After you install the software, start the computer.
Click OK to save the configuration.
Create a server.

Example incorrect usage:

After the software has been installed, the computer can be started.
The configuration is saved when the OK button is clicked.
A server is created by you.

However, passive voice is acceptable in the following situations:

  • Using active voice sounds like you are blaming the user. For example, you can use passive voice in an error message or troubleshooting content when the active subject is the user.
  • The agent of action is unknown, or you want to de-emphasize the agent of action and emphasize the object on which the action is performed.
  • Recasting the sentence in active voice is wordy or awkward.

Example correct usage:

If the build fails, the flavor might have been omitted.
A flag was set incorrectly.
(The messages can be generated by the product, the OS, or the database, and the source of the messages is not important to the user.)
The product, OS, or database returns the messages.

Example incorrect usage:

If the build fails, you probably omitted the flavor.
You set the flag incorrectly.
The messages are returned.

Use present tense

Users read documentation to perform tasks or gather information. For users, these activities take place in their present, so the present tense is appropriate in most cases. Additionally, present tense is easier to read than past or future tense.

Use future tense only when you need to emphasize that something will occur later (from the users' perspective).

Example correct usage:

The product prompts you to verify the deletion.
After you log in, your account begins the verification process.

Example incorrect usage:

The product will prompt you to verify the deletion.
After you log in, your account will then begin the verification process.

Write to you (the user)

Users are more engaged with documentation when you use second person (that is, you address the user as you). Second person promotes a friendly tone by addressing users directly. Using second person with the imperative mood (in which the subject you is understood) and active voice helps to eliminate wordiness and confusion about who or what initiates an action, especially in procedural steps.

Using second person also avoids the use of gender-specific, third-person pronouns such as he, she, his, and hers. If you must use third person, use the pronouns they and their, but ensure that the pronoun matches the referenced noun in number.

Use first person plural pronouns (we, our) judiciously. These pronouns emphasize the writer or OpenStack rather than the user, so before you use them, consider whether second person or imperative mood is more "user friendly." However, use we recommend rather than it is recommended or OpenStack recommends . Also, you can use we in the place of OpenStack if necessary.

Do not use first person to avoid naming the product or to avoid using passive voice. If the product is performing the action, use third person (the product as actor). If you want to de-emphasize the agent of action and emphasize the object on which the action is performed, use passive voice.

The first-person singular pronoun I is acceptable in the question part of FAQs and when authors of blogs or signed articles are describing their own actions or opinions.

Do not switch person (point of view) in the same document.

Example correct usage:

To create a server, you specify a name, flavor, and image.
To create a server, specify a name, flavor, and image. (imperative mood)

Example incorrect usage:

Creating a server involves specifying a name, flavor, and image.
To create a server, the user specifies and name, flavor, and image.

Avoid obscure non-English words and abbreviations

Some non-English words and abbreviations are difficult to translate, and some users might be unfamiliar with them. Some Latin abbreviations, like i.e., e.g., and etc., are unnecessarily vague. The following lists terms and abbreviations to avoid, and their preferred alternatives.

Remove "e.g."

Example correct usage - remove "e.g.":

Create a server by using a Linux distribution. For example, use Fedora or Ubuntu.
Create a server by using a Linux distribution, such as Fedora or Ubuntu.

Example incorrect usage: "e.g."

Create a server by using a Linux distribution, e.g. Fedora or Ubuntu.<br />

Remove "etc."

Example correct usage - remove "etc.":

The dashboard includes metrics such as CPU, network interfaces, and file systems.

Example incorrect usage "etc.":

The dashboard includes metrics such as CPU, network interfaces, file systems, etc.

Terms and usage

This section offers conventions around general English usage and terms that are not covered in the glossary. The glossary is available as reference online.

Miscelleanous words

Use these spellings:

  • plug-in
  • X-as-a-Service (for any X ;)

backend, back end, and back-end

In general, avoid. Use a more specific term such as server, operating system, or network.

However, if you do use it, use back end for the noun and back-end for the adjective.

Do not use backend.

Example

back-end members (adjective)
session back end (noun)

ethernet versus Ethernet

Do not use ethernet. Correct usage is Ethernet.

hostname

Use lowercase unless legal considerations require capitalizing.

Example

"local-hostname": "test.novalocal"

Command line versus command-line

Do not hyphenate command line when it is used as a noun.

Use:

Type the following command at the command line and press Enter.

When used as an adjective, hyphenate it.

Use:

The nova client is a command-line interface (CLI).

Note: If you need to use the spelled-out term for clarity, hyphenate it. However, you can use the abbreviation without first spelling out the term; it is a common abbreviation.

OpenStack, not Openstack or openstack

Service and project names

When referring to the services, use "Compute," "Image Service" and "Identity" instead of "nova," "glance," and "keystone." Use the project names like "nova" and "keystone" when you refer to the project or the command-line interfaces (CLIs) and service names.

Here's the list of project names and their official names and capitalization:

  • Ceilometer: Telemetry or Telemetry module
  • Cinder: OpenStack Block Storage
  • Glance: OpenStack Image Service
  • Heat: Orchestration or Orchestration module
  • Horizon: OpenStack dashboard
  • Keystone: OpenStack Identity
  • Neutron: OpenStack Networking
  • Nova: OpenStack Compute
  • Swift: OpenStack Object Storage

Generally the capitalization of the project team names like swift is lowercase. When used as a command-line-client name, lowercase is best. When used for the team or project name, typically it's not necessary to capitalize.

Release names

Release Names should follow the wiki page. Particularly, the 9th release should be written Icehouse - a single word with only initial capital.

Code conventions

No -y for package install

Do not use the "-y" option for package installation. Correct usage is "apt install package" or "yum install package" or "zypper install package"

Guide Conventions

The following lists conventions used for writing specific guides. In general we want to be consistent between guides, especially since some guides include the same files.

General

  • Mentioning Bugs. If there is a bug that causes some workaround or limitation to be documented, the link to the bug report should be included. This makes it easier to maintain and update such notes.

Install Guide

  • Use controller instead of the controller node management interface IP address 10.0.0.11. Use replaceable for it like <replaceable>controller</replaceable>.
  • Use computeX instead of the compute node management interface IP address for compute nodes. Replace X with a number starting from 1. The management interface IP address of the first compute node is 10.0.0.31, the second is 10.0.0.32, etc.
  • Use blockX instead of the block storage node management interface IP address for block storage nodes. Replace X with a number starting from 1. The management interface IP address of the first block storage node is 10.0.0.41, the second 10.0.0.42, etc.
  • Use objectX instead of the object storage node management interface IP address for object storage nodes. Replace X with a number starting from 1. The management interface IP address of the first object storage node is 10.0.0.51, the second 10.0.0.52, etc.
  • Try to reference the name of a network interface as described in the architecture chapter. For example, say "configure the management interface IP address as 10.0.0.51" rather than "configure eth0 as 10.0.0.51".
  • The example IP addressing structure allows up to 10 controller nodes, network nodes, compute nodes, block storage nodes, and object storage nodes.
  • Database passwords are written as SERVICE_DBPASS, e.g. NOVA_DBPASS
  • Keystone passwords are written as USERNAME_PASS, e.g. GLANCE_PASS
  • rabbit_userid is guest
  • Networking services
    • Use "OpenStack Networking (neutron)" for chapter/section titles and first instance. Use "OpenStack Networking" or "Networking" for additional instances.
    • Use "legacy networking (nova-network)" for chapter/section titles and first instance. Use "legacy networking" for additional instances.
  • Structure for steps that involve commands:
1) Run the following command to install the components:
    a) apt-get install package1 package2
  • Structure for steps that involve configuration:
1) Edit the /etc/abc/abc.conf file:
    a) Configure database access in the [database] section:
        [database]
        ...
        connection = mysql://
    b) Configure RabbitMQ message broker access in the [DEFAULT] section:
        [DEFAULT]
        ...
        rabbit_host = controller
    c) Configure Identity service access in the [keystone_authtoken] section:
        [keystone_authtoken]
        ...
        auth_host = controller
    • Example code snippet for editing /etc/heat/heat.conf:
<procedure os="ubuntu;rhel;centos;fedora;sles;opensuse">
  <title>To configure the Orchestration components</title>
  <para>Edit the <filename>/etc/heat/heat.conf</filename> file and perform
    the following tasks:</para>
  <step>
    <para>Configure database access in the <literal>[database]</literal>
      section.</para>
    <para>Replace <replaceable>HEAT_DBPASS</replaceable> with the password
      you chose for the Orchestration database.</para>
    <programlisting language="ini">[database]
...
connection = mysql://heat:<replaceable>HEAT_DBPASS</replaceable>@<replaceable>controller</replaceable>/heat</programlisting>
  </step>
  <step os="ubuntu;sles;opensuse">
    <para>Configure <application>RabbitMQ</application> message broker
      access in the <literal>[DEFAULT]</literal> section:</para>
    <para>Replace <replaceable>RABBIT_PASS</replaceable> with the password
      you chose for the <literal>guest</literal> account in
      <application>RabbitMQ</application>.</para>
    <programlisting language="ini">[DEFAULT]
...
rpc_backend = heat.openstack.common.rpc.impl_kombu
rabbit_host = <replaceable>controller</replaceable>
rabbit_password = <replaceable>RABBIT_PASS</replaceable></programlisting>
  </step>
</procedure>

Operations Guide

The Operations Guide follows for some cases the O'Reilly style guide.

Source file names and xml:id creation

For file names, use bk_, ch_, section_, and app_ at the beginning of the file name to indicate the type of file it is in the hierarchy of the build. For further organization, you can use subdirectories to organize the files by a particular grouping such as project or topic.

For xml:id creation, follow these guidelines:

  • xml:id must be unique across a built deliverable, otherwise you get build errors
  • xml:id creates the HTML file name so it should be human-readable, not codified like the file name
  • xml:id should closely follow the actual title in the text, using dashes for spaces
  • xml:id creation should consider search and find-ability as well as human-readability

JSON formatting conventions

Format JSON files to be human readable. Use four spaces for indentation (matching OpenStack conventions used in Python and shell scripts), and one space after the name-separator (colon). Obey the formal JSON format; in particular, strings are in double (not single) quotes.

Sample files may have their keys ordered if that makes the file easier to understand. Automatic reformatting tools are to preserve the order of keys.

Example:

{
    "uuid": "d8e02d56-2648-49a3-bf97-6be8f1204f38",
    "availability_zone": "nova",
    "hostname": "test.novalocal",
    "launch_index": 0,
    "array0": [],
    "array1": [
        "low"
    ],
    "array3": [
        "low",
        "high",
        "mid"
    ],
    "object0": {},
    "object1": {
        "value": "low",
        "role": "some"
    },
    "name": "test"
}