Use Second Person and Imperative Mood

Write to the User

Users are more engaged with content when it talks to them directly. Use second person to talk to users directly, addressing the user as you. Second person promotes a friendly tone.

• Use second person with the imperative mood (in which the subject you is understood) and active voice to eliminate wordiness and confusion about who or what initiates an action, especially in procedural steps.

  Tip

  All of the guidelines in this list, and most of the guidelines in the style guide, use second person, imperative mood, and active voice.

• Use second person to avoid the use of gender-specific, third-person pronouns:

  he she

  his hers

  him her

  himself herself

  If you must use third person, use the pronouns:

  they

  them

  their

  themselves

  Verify that the pronoun's antecedent is plural.

  Using third person rarely makes sense. Second person should address most reference and instructional material.

• Use first-person plural pronouns (we, our) judiciously. These pronouns emphasize the writer or MongoDB rather than the user. Before using first-person pronouns, consider second person or imperative mood instead.

  • Use we recommend rather than it's recommended or MongoDB recommends. Limit how often you state recommendations. This expresses an opinion on behalf of MongoDB. Make sure that the engineering team or TSE team has expressed this opinion before stating anything as a recommendation. You should be prepared to defend any recommendations you publish with a ticket number from engineering or the TSE organization.

  • You can use we in the place of MongoDB if necessary.

• Use the first-person singular pronoun I only in the question part of FAQs.

• Avoid switching person (point of view) in the same document.

Avoid the Subjunctive Mood

The subjunctive mood expresses doubt. That doesn’t engender trust from readers about our content! Avoid words that imply uncertainty:

• should

• could

• would

Readers expect documentation to be authoritative. If you don't know which one of two options is correct, research or ask engineering to find the exact answer. Document what you discover. Don't use language that gives the user more questions.