1
1
.. _write-to-the-user:
2
+ .. _sg-second-person:
3
+ .. _sg-imperative-mood:
2
4
3
5
=====================================
4
6
Use Second Person and Imperative Mood
5
7
=====================================
6
8
9
+ .. default-domain:: mongodb
10
+
7
11
.. include:: /includes/styles/corrections.rst
8
12
9
- Users are more engaged with content when it talks to them directly. You
10
- talk to users directly by using *second person*, addressing the user as
13
+ Write to the User
14
+ -----------------
15
+
16
+ Users are more engaged with content when it talks to them directly. Use
17
+ *second person* to talk to users directly, addressing the user as
11
18
*you*. Second person promotes a friendly tone.
12
19
13
20
- Use second person with the imperative mood (in which the subject
@@ -22,26 +29,54 @@ talk to users directly by using *second person*, addressing the user as
22
29
voice.
23
30
24
31
- Use second person to avoid the use of gender-specific, third-person
25
- pronouns such as *he*, *she*, *his*, and *hers*. If you must use
26
- third person, use the pronouns *they* and *their*, but ensure that
27
- the noun that the pronoun refers to is plural.
32
+ pronouns:
33
+
34
+ .. hlist::
35
+ :columns: 4
36
+
37
+ - *he*
38
+ - *she*
39
+ - *his*
40
+ - *hers*
41
+ - *him*
42
+ - *her*
43
+ - *himself*
44
+ - *herself*
45
+
46
+ If you must use third person, use the pronouns:
47
+
48
+ .. hlist::
49
+ :columns: 4
50
+
51
+ - *they*
52
+ - *them*
53
+ - *their*
54
+ - *themselves*
55
+
56
+ Verify that the pronoun's antecedent is plural.
57
+
58
+ Using third person rarely makes sense. Second person should address
59
+ most reference and instructional material.
28
60
29
61
- Use first-person plural pronouns (*we*, *our*) judiciously. These
30
- pronouns emphasize the writer or MongoDB rather than the user, so
31
- before you use them , consider whether second person or imperative
32
- mood would be more "user friendly."
62
+ pronouns emphasize the writer or MongoDB rather than the user.
63
+ Before using first-person pronouns , consider second person or
64
+ imperative mood instead.
33
65
34
66
- Use *we recommend* rather than *it's recommended* or *MongoDB
35
- recommends*.
67
+ recommends*. Limit how often you state recommendations. This
68
+ expresses an opinion on behalf of MongoDB. Make sure that the
69
+ engineering team or TSE team has expressed this opinion before
70
+ stating anything as a recommendation. You should be prepared to
71
+ defend any recommendations you publish with a ticket number from
72
+ engineering or the TSE organization.
73
+
36
74
- You can use *we* in the place of *MongoDB* if necessary.
37
75
38
76
- Use the first-person singular pronoun *I* only in the question part
39
- of FAQs and when authors of blogs or signed articles are describing
40
- their own actions or opinions.
77
+ of FAQs.
41
78
42
- - Avoid switching person (point of view) in the same document. You can
43
- switch person in blog posts that use first-person singular but then
44
- switch to second person for instructional steps.
79
+ - Avoid switching person (point of view) in the same document.
45
80
46
81
.. list-table::
47
82
:widths: 50 50
@@ -50,16 +85,18 @@ talk to users directly by using *second person*, addressing the user as
50
85
* - Use
51
86
- Avoid
52
87
53
- * - To create a server , specify a name, flavor, and image .
88
+ * - To create a cluster , specify a name and tier .
54
89
(imperative)
55
90
56
- To create a server, you specify a name, flavor, and image.
57
- - Creating a server involves specifying a name, flavor, and image.
91
+ To create a cluster, you specify a name and tier.
58
92
59
- To create a server, the user specifies and name, flavor, and image .
93
+ - Creating a cluster involves specifying a name and tier .
60
94
61
- * - Click **Yes** to accept the license agreement.
62
- - The license agreement is accepted when the user clicks **Yes**.
95
+ To create a cluster, the user specifies and name and tier.
96
+
97
+ * - Click :guilabel:`Yes` to accept the license agreement.
98
+ - The license agreement is accepted when the user clicks
99
+ :guilabel:`Yes`.
63
100
64
101
* - We offer you a comprehensive portfolio of hosting options.
65
102
- MongoDB offers a comprehensive portfolio of hosting options for
@@ -72,8 +109,12 @@ talk to users directly by using *second person*, addressing the user as
72
109
73
110
>>>>>>> 0e2947b... (DOCSP-7337): Updates to Writing Guide ahead of LGTM process.
74
111
* - Providing you a fantastic experience sets MongoDB apart. We are
112
+ <<<<<<< HEAD
75
113
>>>>>>> 9614a09... (DOCSP-6719): Updated Style Guide starting with port of Rackspace Style Guide.
76
114
here to help, 24x7x365.
115
+ =======
116
+ here to help, 24×7×365.
117
+ >>>>>>> d2fdf9a... (DOCSP-11369) Update Person and Mood page
77
118
- MongoDB is here to help customers.
78
119
79
120
* - Cloud Backup uses block-level deduplication, which means that
@@ -89,11 +130,14 @@ talk to users directly by using *second person*, addressing the user as
89
130
.. _subjunctive-mood:
90
131
91
132
Avoid the Subjunctive Mood
92
- ~~~~~~~~~~~~~~~~~~~~~~~~~~
133
+ --------------------------
93
134
94
135
The subjunctive mood expresses doubt. *That doesn’t engender trust from
95
- readers about our content!* Avoid words like “should” and “could”; they
96
- imply uncertainty.
136
+ readers about our content!* Avoid words that imply uncertainty:
137
+
138
+ - should
139
+ - could
140
+ - would
97
141
98
142
.. list-table::
99
143
:widths: 50 50
@@ -103,10 +147,26 @@ imply uncertainty.
103
147
* - Use
104
148
- Avoid
105
149
106
- * - The logs download as a .CSV file.
107
- - The logs should download as a .CSV file.
150
+ * - The logs download as a `` .CSV`` file.
151
+ - The logs should download as a `` .CSV`` file.
108
152
109
153
* - If you install the MongoDB Agent, you can manage your deployment
110
154
with Automation.
111
155
- If you were to install the MongoDB agent, you could manage your
112
156
deployment with Automation.
157
+
158
+ Readers expect documentation to be authoritative. If you don't know
159
+ which one of two options is correct, research or ask engineering to
160
+ find the exact answer. Document what you discover. Don't use language
161
+ that gives the user more questions.
162
+
163
+ .. note::
164
+
165
+ Production notes and other similar resources where we recommend best practices configuration settings for use with MongoDB offerings.
166
+
167
+ .. example::
168
+
169
+ You should set your ``vm.swappiness`` to ``1`` if possible.
170
+
171
+ This language presents an ideal configuration, but does not
172
+ *mandate* it.
0 commit comments