Jump to: navigation, search

Documentation/Conventions

< Documentation
Revision as of 02:11, 11 November 2014 by Fifieldt (talk | contribs) (Terms and usage)

This page lists conventions that the Docs team follows for writing documentation. Additionally, the IBM Style Guide is used as reference. In case of conflicts between these two, the wiki convention pages takes precedence. Before you add new rules here, discuss it with the rest of the Docs team and reach consensus.

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. Additionally, use the IBM Terminology as reference.

Miscellaneous 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
  • ironic: Bare metal module for OpenStack
  • keystone: OpenStack Identity
  • neutron: OpenStack Networking
  • nova: OpenStack Compute
  • sahara: Data processing service for OpenStack
  • swift: OpenStack Object Storage
  • trove: Database Service for OpenStack

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-get install package" or "yum install package" or "zypper install package"

Client arguments: "--option ARGUMENT"

The OpenStack CLI commands like keystone support both --option ARGUMENT and --option=ARGUMENT. The preferred way is --option ARGUMENT.

euca2ools documentation

Because Nova exposes both its own API and an EC2-compatible API, many tasks can be completed by using either the nova CLI or euca2ools. Documentation related to euca2ools should generally be limited to:

  • Describing how to get credentials to work with euca2ools
  • Describing differences between how Amazon's EC2 endpoint behaves and how an OpenStack endpoint behaves when accessing via EC2.