General writing guidelines

OpenStack requires contributions to be released under the
Apache 2.0 license, and have licensing information in the header when
uploaded to the public code repository. This submission method makes
all contributions immediately available to all community members
under the Apache 2.0 license. See
Licensing requirements
for more information.

Use standard United States (U.S.) English throughout all technical
publications. When in doubt about the spelling of a word, consult the
Merriam-Webster’s Collegiate Dictionary and the
IBM developerWorks editorial style guide.

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

Do not use

Use

After the software has been
installed, the computer can be
started.

After you install the software,
start the computer.

The Configuration is saved when
you click OK.

Click OK to save the
configuration.

A server is created by you.

Create a server.

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.

Example of usage

Do not use

Use

If the build fails, you probably
omitted the flavor.

If the build fails, the flavor
might have been omitted.

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.

Example of usage

Do not use

Use

The product, OS, or database
returns the messages.

The messages are returned [by the
database].

Recasting the sentence in active voice is wordy or awkward.

Example of usage

Do not use

Use

In 2009, engineers developed a
software that simplifies the
installation.

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, the present tense is easier to read
than the past or future tense.

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

Example of usage

Do not use

Use

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

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

Users are more engaged with documentation when you use second person (that is,
you address the user as “you”).

Writing in second person has the following advantages:

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