Skip to content

Commit 9dd82cc

Browse files
Anthony Sansoneatsansone
authored andcommitted
(DOCSP-11369) Update Person and Mood page
1 parent b2980ad commit 9dd82cc

File tree

2 files changed

+105
-38
lines changed

2 files changed

+105
-38
lines changed

source/style-guide/writing/use-effective-verbs.txt

Lines changed: 20 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -131,7 +131,6 @@ verbs, use them accurately and consistently:
131131
:widths: 10 45 45
132132
:header-rows: 1
133133

134-
135134
* - Modal verb
136135
- Description
137136
- Example
@@ -150,15 +149,17 @@ verbs, use them accurately and consistently:
150149
- A service **might** expose endpoints in different regions.
151150

152151
* - must
153-
- Indicates the necessity of an action. In general, use the
154-
imperative mood. It implies the subject *you* and doesn't
155-
require *must* but still indicates necessity.
152+
- Indicates the necessity of an action.
153+
154+
In general, use the imperative mood. It implies the subject
155+
*you* and doesn't require *must* but still indicates necessity.
156156
- The worker **must** delete the message when work is done.
157157

158158
* - should
159-
- Indicates a recommendation or an expectation. Avoid using
160-
should, because it implies uncertainty or could imply a best
161-
practice (which we might or might not want to do).
159+
- Indicates a recommendation or an expectation.
160+
161+
Avoid using should, because it implies uncertainty or could
162+
imply a best practice (which we might or might not want to do).
162163
- To avoid losing a claim in the middle of processing a message,
163164
clients **should** periodically renew claims during long-running
164165
batches of work.
@@ -169,9 +170,12 @@ Use Single-Word Verbs
169170
~~~~~~~~~~~~~~~~~~~~~
170171

171172
When possible, use single-word verbs rather than phrasal verbs (verbs
172-
followed by prepositions or adverbs). For example, use *omit* rather
173-
than *leave out*, or shorten *start up* to *start*. One-word verbs are
174-
easier to understand and to translate.
173+
followed by prepositions or adverbs).
174+
175+
.. example::
176+
177+
Use *omit* rather than *leave out*, or shorten *start up* to
178+
*start*. One-word verbs are easier to understand and to translate.
175179

176180
If you must use a phrasal verb, keep the parts of the verb together
177181
unless that changes the meaning of the sentence. Some acceptable
@@ -180,9 +184,12 @@ around*.
180184

181185
.. note::
182186

183-
Don't turn a phrasal verb into a single-word verb. For example,
184-
don't use *login*, *setup*, or *workaround* as verbs. These
185-
single-word terms should be used only as nouns or adjectives.
187+
Don't turn a phrasal verb into a single-word verb.
188+
189+
.. example::
190+
191+
Don't use *login*, *setup*, or *workaround* as verbs. These
192+
single-word terms should be used only as nouns or adjectives.
186193

187194
.. list-table::
188195
:widths: 50 50
Lines changed: 85 additions & 25 deletions
Original file line numberDiff line numberDiff line change
@@ -1,13 +1,20 @@
11
.. _write-to-the-user:
2+
.. _sg-second-person:
3+
.. _sg-imperative-mood:
24

35
=====================================
46
Use Second Person and Imperative Mood
57
=====================================
68

9+
.. default-domain:: mongodb
10+
711
.. include:: /includes/styles/corrections.rst
812

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
1118
*you*. Second person promotes a friendly tone.
1219

1320
- 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
2229
voice.
2330

2431
- 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.
2860

2961
- 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.
3365

3466
- 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+
3674
- You can use *we* in the place of *MongoDB* if necessary.
3775

3876
- 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.
4178

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

4681
.. list-table::
4782
:widths: 50 50
@@ -50,16 +85,18 @@ talk to users directly by using *second person*, addressing the user as
5085
* - Use
5186
- Avoid
5287

53-
* - To create a server, specify a name, flavor, and image.
88+
* - To create a cluster, specify a name and tier.
5489
(imperative)
5590

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

59-
To create a server, the user specifies and name, flavor, and image.
93+
- Creating a cluster involves specifying a name and tier.
6094

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`.
63100

64101
* - We offer you a comprehensive portfolio of hosting options.
65102
- 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
72109

73110
>>>>>>> 0e2947b... (DOCSP-7337): Updates to Writing Guide ahead of LGTM process.
74111
* - Providing you a fantastic experience sets MongoDB apart. We are
112+
<<<<<<< HEAD
75113
>>>>>>> 9614a09... (DOCSP-6719): Updated Style Guide starting with port of Rackspace Style Guide.
76114
here to help, 24x7x365.
115+
=======
116+
here to help, 24×7×365.
117+
>>>>>>> d2fdf9a... (DOCSP-11369) Update Person and Mood page
77118
- MongoDB is here to help customers.
78119

79120
* - 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
89130
.. _subjunctive-mood:
90131

91132
Avoid the Subjunctive Mood
92-
~~~~~~~~~~~~~~~~~~~~~~~~~~
133+
--------------------------
93134

94135
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
97141

98142
.. list-table::
99143
:widths: 50 50
@@ -103,10 +147,26 @@ imply uncertainty.
103147
* - Use
104148
- Avoid
105149

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

109153
* - If you install the MongoDB Agent, you can manage your deployment
110154
with Automation.
111155
- If you were to install the MongoDB agent, you could manage your
112156
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

Comments
 (0)