Documentation/Conventions
Contents
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.
Correct usage
After you install the software, start the computer.
Click OK to save the configuration.
Create a server.
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.
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.
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).
Correct usage
The product prompts you to verify the deletion.
After you log in, your account begins the verification process.
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.
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)
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 table lists terms and abbreviations to avoid, and their preferred alternatives.
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.
Incorrect usage "e.g."
Create a server by using a Linux distribution, e.g. Fedora or Ubuntu.
Correct usage - remove "etc."
The dashboard includes metrics such as CPU, network interfaces, and file systems.
Incorrect usage "etc."
The dashboard includes metrics such as CPU, network interfaces, file systems, etc.
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"
DocBook markup conventions
Documentation/Conventions/DocBook_markup_conventions
