You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: contribute-docs/style-guide/grammar-spelling.md
+24-21Lines changed: 24 additions & 21 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -5,9 +5,9 @@ description: Guidelines for using correct grammar and spelling in your writing.
5
5
6
6
# Grammar and spelling
7
7
8
-
## Pronouns do's and don'ts
8
+
## Pronouns do's and don'ts
9
9
10
-
### Be unambiguous
10
+
### Be unambiguous
11
11
12
12
In order to make your sentences as clear as possible when using pronouns, they should always be unambiguous.
13
13
@@ -23,9 +23,9 @@ And while we're at it, let's remove the *in order* since it doesn't really add a
23
23
24
24
### Use second-person pronouns (*you*, *your*, *yours*)
25
25
26
-
In general, write in the second person to establish a friendly, casual tone with the reader as though you're speaking to them. Writing in the second person also helps you avoid using passive voice. However, don't overuse *your* when referring to user interaction.
26
+
In general, write in the second person to establish a friendly, casual tone with the reader as though you're speaking to them. Writing in the second person also helps you avoid using passive voice. However, don't overuse *your* when referring to user interaction.
27
27
28
-
For example: *Your Elastic Agents* can feel overly familiar if used too many times. However, *your environment* as opposed to *the environment* sounds more casual. It can be tricky when deciding word choice, but when in doubt, try replacing the pronoun with *the* to see if it's an appropriate substitute.
28
+
For example: *Your Elastic Agents* can feel overly familiar if used too many times. However, *your environment* as opposed to *the environment* sounds more casual. It can be tricky when deciding word choice, but when in doubt, try replacing the pronoun with *the* to see if it's an appropriate substitute.
29
29
30
30
:::{dropdown} Examples
31
31
* Log in to your account to display the settings.
@@ -34,40 +34,40 @@ For example: *Your Elastic Agents* can feel overly familiar if used too many tim
34
34
35
35
### Use singular first-person pronouns sparingly (*I*, *me*, *my*, *mine*)
36
36
37
-
Typically, you should never write in the first person. You can, however, use first-person pronouns if they appear in the product UI.
37
+
Typically, you should never write in the first person. You can, however, use first-person pronouns if they appear in the product UI.
38
38
39
39
:::{dropdown} Example
40
-
Select the checkbox that says, "Confirm my selection."
40
+
Select the checkbox that says, "Confirm my selection."
41
41
:::
42
42
43
-
### Use plural first-person pronouns wisely (*we*, *us*, *our*, *our*)
43
+
### Use plural first-person pronouns wisely (*we*, *us*, *our*, *our*)
44
44
45
-
First-person plural pronouns can sometimes convey a stuffy and serious tone—the opposite of Elastic's more casual tone. In some instances, however, it's okay to use these sparingly. For example, it's perfectly acceptable to say *we recommend*, and in fact is preferable over *it is recommended* since that uses passive voice.
45
+
First-person plural pronouns can sometimes convey a stuffy and serious tone—the opposite of Elastic's more casual tone. In some instances, however, it's okay to use these sparingly. For example, it's perfectly acceptable to say *we recommend*, and in fact is preferable over *it is recommended* since that uses passive voice.
46
46
47
47
### Avoid gendered pronouns
48
48
49
49
Use gender-neutral pronouns as appropriate. Avoid using *he*, *him*, *his*, *she*, and *her*. Instead, try replacing it with a form of *user*. Also, avoid using combination pronouns such as *he/she* or *(s)he*. Use *they* or *them* instead.
50
50
51
-
## Verb tense
51
+
## Verb tense
52
52
53
53
Avoid temporal words like *currently*, *now*, or *will* and conditional words like *should* or *could*. Write in the present tense to describe the state of the product as it is now. You may need to use the past tense occasionally, but try to change it to the present tense to see if that's a better fit.
54
54
55
55
:::{dropdown} Example
56
56
❌ **Don't**: If you didn't select all the required permissions, an error message will appear.
57
57
58
-
✔️ **Do**: If you don't select all the required permissions, an error message appears.
58
+
✔️ **Do**: If you don't select all the required permissions, an error message appears.
59
59
:::
60
60
61
61
## Contraction do's and dont's
62
62
63
-
Use contractions: they're (an acceptable contraction, by the way) conversational and don't require a lot of thought because we use them in everyday language. However, don't mix contractions and their spelled-out equivalents. For example, don't use *don't* and *do not* in the same context unless you absolutely need the latter for emphasis.
63
+
Use contractions: they're (an acceptable contraction, by the way) conversational and don't require a lot of thought because we use them in everyday language. However, don't mix contractions and their spelled-out equivalents. For example, don't use *don't* and *do not* in the same context unless you absolutely need the latter for emphasis.
64
64
65
-
Don't use Elastic references as a contraction to replace *Elastic is*.
65
+
Don't use Elastic references as a contraction to replace *Elastic is*.
66
66
67
67
:::{dropdown} Example
68
68
❌ **Don't**: Elastic's excited to release this new feature.
69
69
70
-
✔️ **Do**: Elastic's new feature helps you find information fast.
70
+
✔️ **Do**: Elastic's new feature helps you find information fast.
71
71
:::
72
72
73
73
Avoid ambiguous or awkward contractions, such as *there'd*, *it'll*, and *they'd*.
@@ -96,7 +96,7 @@ Avoid gerunds in prepositional phrases—this will make your instructions easier
96
96
✔️ **Do**: Refer to instructions on how to configure the Elastic Agent.
97
97
:::
98
98
99
-
## Punctuation
99
+
## Punctuation
100
100
101
101
### Colons
102
102
@@ -184,17 +184,19 @@ Use a hyphen:
184
184
* When a prefixed word has two vowels together.
185
185
186
186
:::{dropdown} Examples
187
-
* Re-enable
188
-
* Pre-approve
187
+
188
+
* Re-enable
189
+
* Pre-approve
189
190
:::
190
191
191
192
* When two or more words modify the following noun, making a compound adjective.
192
193
193
194
:::{dropdown} Examples
194
-
* Real-time results
195
-
* AI-generated text
196
-
* User-defined values
197
-
* Up-to-date environment
195
+
196
+
* Real-time results
197
+
* AI-generated text
198
+
* User-defined values
199
+
* Up-to-date environment
198
200
:::
199
201
200
202
* Whenever the prefix is `self-`, `ex-`, or `all-`.
@@ -206,7 +208,8 @@ Use a hyphen:
206
208
* For a minus sign and to indicate negative numbers. In formulas and equations, add spacing between the numbers and arithmetic operators. For negative numbers, don't add spacing between the minus and the number.
0 commit comments