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
+45-45Lines changed: 45 additions & 45 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -53,9 +53,9 @@ Use gender-neutral pronouns as appropriate. Avoid using *he*, *him*, *his*, *she
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
-
❌ **Don't**: If you didn't select all the required permissions, an error message will appear.
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
@@ -65,9 +65,9 @@ Use contractions: they're (an acceptable contraction, by the way) conversational
65
65
Don't use Elastic references as a contraction to replace *Elastic is*.
66
66
67
67
:::{dropdown} Example
68
-
❌ **Don't**: Elastic's excited to release this new feature.
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*.
@@ -91,9 +91,9 @@ Secure your cluster
91
91
Avoid gerunds in prepositional phrases—this will make your instructions easier to understand. Also avoid gerunds in instructional/procedural sentences or headings.
92
92
93
93
:::{dropdown} Example
94
-
❌ **Don't**: Refer to instructions on configuring the Elastic Agent.
95
-
96
-
✔️ **Do**: Refer to instructions on how to configure the Elastic Agent.
94
+
❌ **Don't**: Refer to instructions on configuring the Elastic Agent.
95
+
96
+
✔️ **Do**: Refer to instructions on how to configure the Elastic Agent.
97
97
:::
98
98
99
99
## Punctuation
@@ -152,25 +152,25 @@ Use commas:
152
152
* When an independent clause and a dependent clause are separated by a coordinating conjunction (*and*, *but*, *or*, *nor*, *fo*r, *so*, or *yet*).
153
153
154
154
:::{dropdown} Examples
155
-
❌ **Don't**: The rule runs every 5 minutes, but analyzes the documents added to indices during the last 6 minutes.
155
+
❌ **Don't**: The rule runs every 5 minutes, but analyzes the documents added to indices during the last 6 minutes.
156
156
157
-
✔️ **Do**: The rule runs every 5 minutes but analyzes the documents added to indices during the last 6 minutes.
157
+
✔️ **Do**: The rule runs every 5 minutes but analyzes the documents added to indices during the last 6 minutes.
158
158
159
-
❌ **Don't**: A custom query rule searches the defined indices, and creates an alert when a document matches the rule's KQL query.
159
+
❌ **Don't**: A custom query rule searches the defined indices, and creates an alert when a document matches the rule's KQL query.
160
160
161
-
✔️ **Do**: A custom query rule searches the defined indices and creates an alert when a document matches the rule's KQL query.
161
+
✔️ **Do**: A custom query rule searches the defined indices and creates an alert when a document matches the rule's KQL query.
162
162
:::
163
163
164
164
* To set off defining relative clauses.
165
165
166
166
:::{dropdown} Examples
167
-
❌ **Don't**: You must use a data view, whose index pattern matches `servers-europe-*`.
167
+
❌ **Don't**: You must use a data view, whose index pattern matches `servers-europe-*`.
168
168
169
-
✔️ **Do**: You must use a data view whose index pattern matches `servers-europe-*`.
169
+
✔️ **Do**: You must use a data view whose index pattern matches `servers-europe-*`.
170
170
171
-
❌ **Don't**: To roll back, you must have a backup snapshot, that includes the `kibana` feature state.
171
+
❌ **Don't**: To roll back, you must have a backup snapshot, that includes the `kibana` feature state.
172
172
173
-
✔️ **Do**: To roll back, you must have a backup snapshot that includes the `kibana` feature state.
173
+
✔️ **Do**: To roll back, you must have a backup snapshot that includes the `kibana` feature state.
174
174
:::
175
175
176
176
### Dashes and hyphens
@@ -218,25 +218,25 @@ Use a hyphen:
218
218
* For predicate adjectives (compound modifiers that come after the word they modify).
219
219
220
220
:::{dropdown} Examples
221
-
❌ **Don't**: Ensure your environment is up-to-date.
221
+
❌ **Don't**: Ensure your environment is up-to-date.
222
222
223
-
✔️ **Do**: Ensure your environment is up to date.
223
+
✔️ **Do**: Ensure your environment is up to date.
224
224
225
-
❌ **Don't**: The values are user-defined.
225
+
❌ **Don't**: The values are user-defined.
226
226
227
-
✔️ **Do**: The values are user defined.
227
+
✔️ **Do**: The values are user defined.
228
228
:::
229
229
230
230
* For compounds with an adverb ending in `-ly`.
231
231
232
232
:::{dropdown} Examples
233
-
❌ **Don't**: Newly-installed Agent
233
+
❌ **Don't**: Newly-installed Agent
234
234
235
-
✔️ **Do**: Newly installed Agent
235
+
✔️ **Do**: Newly installed Agent
236
236
237
-
❌ **Don't**: Publicly-exposed storage buckets
237
+
❌ **Don't**: Publicly-exposed storage buckets
238
238
239
-
✔️ **Do**: Publicly exposed storage buckets
239
+
✔️ **Do**: Publicly exposed storage buckets
240
240
:::
241
241
242
242
#### En dashes
@@ -262,8 +262,8 @@ Use an en dash:
262
262
Use em dashes to indicate a break in the flow of a sentence. Don't add spaces around an em dash.
263
263
264
264
:::{dropdown} Examples
265
-
* Consider adding exceptions—preferably with a combination of user agent and IP address conditions.
266
-
* Filter out endpoint events that you don't want to store—for example, high-volume events.
265
+
* Consider adding exceptions—preferably with a combination of user agent and IP address conditions.
266
+
* Filter out endpoint events that you don't want to store—for example, high-volume events.
267
267
:::
268
268
269
269
### Parentheses
@@ -273,8 +273,8 @@ Before using parentheses, consider if you can replace them with dashes, semicolo
273
273
Use parentheses for abbreviations and acronyms after spelling them out.
274
274
275
275
:::{dropdown} Examples
276
-
* Monitor the security posture of your cloud assets using the Cloud Security Posture Management (CSPM) feature.
277
-
* Expand a risk level group (for example, **High**) or an asset criticality group (for example, **high_impact**).
276
+
* Monitor the security posture of your cloud assets using the Cloud Security Posture Management (CSPM) feature.
277
+
* Expand a risk level group (for example, **High**) or an asset criticality group (for example, **high_impact**).
278
278
:::
279
279
280
280
### Semicolons
@@ -284,8 +284,8 @@ In general, try to simplify complex sentences to avoid using semicolons.
284
284
Where necessary, use a semicolon to join two closely related independent clauses where a period or a comma is not as effective.
285
285
286
286
:::{dropdown} Examples
287
-
* The endpoint is idempotent; therefore, it can safely be used to poll a given migration and, upon completion, finalize it.
288
-
* Multiple consecutive dashes in the value must be escaped; single dashes do not need to be escaped.
287
+
* The endpoint is idempotent; therefore, it can safely be used to poll a given migration and, upon completion, finalize it.
288
+
* Multiple consecutive dashes in the value must be escaped; single dashes do not need to be escaped.
289
289
:::
290
290
291
291
## Spelling
@@ -360,17 +360,17 @@ Follow the standard capitalization rules for American English. In general, use s
360
360
❌ Don't capitalize the spelled-out form of an acronym unless it's a proper noun or is conventionally capitalized.
361
361
362
362
:::{dropdown} Examples
363
-
❌ **Don't**: This tab shows anomalies discovered by Machine Learning (ML) jobs.
363
+
❌ **Don't**: This tab shows anomalies discovered by Machine Learning (ML) jobs.
364
364
365
-
✔️ **Do**: This tab shows anomalies discovered by machine learning (ML) jobs.
365
+
✔️ **Do**: This tab shows anomalies discovered by machine learning (ML) jobs.
366
366
:::
367
367
368
368
❌ Don't capitalize API names.
369
369
370
370
:::{dropdown} Examples
371
-
❌ **Don't**: The Bulk API makes it possible to perform many index/delete operations in a single API call.
371
+
❌ **Don't**: The Bulk API makes it possible to perform many index/delete operations in a single API call.
372
372
373
-
✔️ **Do**: The bulk API makes it possible to perform many index/delete operations in a single API call.
373
+
✔️ **Do**: The bulk API makes it possible to perform many index/delete operations in a single API call.
374
374
:::
375
375
376
376
## Abbreviations and acronyms
@@ -382,21 +382,21 @@ In general, spell out abbreviations when a term is unlikely to be familiar to th
382
382
Avoid using an abbreviation for the first time in a title or heading, unless you need to match the UI, for example. If the first use of the abbreviation is in a title or heading, introduce the abbreviation (in parentheses, following the spelled-out term) in the following body text.
383
383
384
384
:::{dropdown} Examples
385
-
❌ **Don't**: ECS field reference
385
+
❌ **Don't**: ECS field reference
386
386
387
-
✔️ **Do**: Elastic Common Schema field reference
387
+
✔️ **Do**: Elastic Common Schema field reference
388
388
389
-
✔️ **Do**: Create an ES|QL rule (OK to use abbreviation since this is how the rule type appears in the UI)
389
+
✔️ **Do**: Create an ES|QL rule (OK to use abbreviation since this is how the rule type appears in the UI)
390
390
:::
391
391
392
392
### Capitalization of abbreviations
393
393
394
394
Capitalize the spelled-out version of the abbreviation only if it's a proper noun or is conventionally capitalized. That is, don't capitalize it only because the abbreviation includes capital letters.
395
395
396
396
:::{dropdown} Examples
397
-
❌ **Don't**: This setting determines whether Cross-Cluster Search (CCS) privilege warnings are displayed.
397
+
❌ **Don't**: This setting determines whether Cross-Cluster Search (CCS) privilege warnings are displayed.
398
398
399
-
✔️ **Do**: This setting determines whether cross-cluster search (CCS) privilege warnings are displayed.
399
+
✔️ **Do**: This setting determines whether cross-cluster search (CCS) privilege warnings are displayed.
400
400
:::
401
401
402
402
### Making abbreviations plural
@@ -406,29 +406,29 @@ When making them plural, treat abbreviations as regular words. Do not use an apo
406
406
If the abbreviation ends in `-s`, `-sh`, `-ch`, or `-x`, then add `-es`.
407
407
408
408
:::{dropdown} Examples
409
-
❌ **Don't**: API's, SDK's, OS'es
409
+
❌ **Don't**: API's, SDK's, OS'es
410
410
411
-
✔️ **Do**: APIs, SDKs, OSes
411
+
✔️ **Do**: APIs, SDKs, OSes
412
412
:::
413
413
414
414
### Using the right article
415
415
416
416
The article (*a* or *an*) you use in front of an abbreviation depends on how the abbreviation is pronounced, not how it's spelled.
417
417
418
418
:::{dropdown} Examples
419
-
❌ **Don't**: a HTML file, a SQL database
419
+
❌ **Don't**: a HTML file, a SQL database
420
420
421
-
✔️ **Do**: an HTML file, an SQL database
421
+
✔️ **Do**: an HTML file, an SQL database
422
422
:::
423
423
424
424
### Latin abbreviations
425
425
426
426
Avoid Latin abbreviations for common English phrases, unless space is limited.
0 commit comments