Grammar and spelling

Correct grammar and consistent spelling reduce ambiguity and help readers focus on the content rather than stumbling over errors. These conventions also support localization and translation efforts.

In order to make your sentences as clear as possible when using pronouns, they should always be unambiguous.

Pronouns provide a wonderful kind of shorthand so that we don't need to repeat lengthy terms over and over. But they can also cause confusion. In the first sentence, readers might be puzzled about whether the pronoun they refers to your sentences or to pronouns.

To remedy this, let's reorganize the sentence so that we don't need the they pronoun at all:

"In order to make your sentences as clear as possible, avoid using ambiguous pronouns".

And while we're at it, let's remove the in order since it doesn't really add anything:

"To make your sentences as clear as possible, avoid using ambiguous pronouns".

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.

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.

Typically, you should never write in the first person. You can, however, use first-person pronouns if they appear in the product UI.

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.

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.

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.

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.

Don't use Elastic references as a contraction to replace Elastic is.

Avoid ambiguous or awkward contractions, such as there'd, it'll, and they'd.

A gerund is a verb form that ends in -ing and acts as a noun. Use gerunds or action verbs in titles that describe tasks. Use gerunds in top-level topic titles, but use action verbs in lower-level titles, especially in sections with many subtasks.

Avoid gerunds in prepositional phrases—this will make your instructions easier to understand. Also avoid gerunds in instructional/procedural sentences or headings.

Use a colon at the end of a sentence or phrase that introduces a list. If a list item is followed by a description, use a colon to introduce the description.

Use commas:

• Before the conjunction in a list of three or more items (also known as Oxford comma).

• After an introductory word or phrase.

• To join independent clauses with a coordinating conjunction (and, but, or, nor, for, so, or yet).

• When an adverbial dependent clause comes before an independent clause.

• To set off non-defining relative clauses (also known as non-restrictive or parenthetical clauses).

❌ Don't use commas:

• When an independent clause and a dependent clause are separated by a coordinating conjunction (and, but, or, nor, for, so, or yet).

• To set off defining relative clauses.

Hyphens compound words, word elements, or numbers to change their meaning.

Use a hyphen:

• When a prefixed word has two vowels together.

• When two or more words modify the following noun, making a compound adjective.

• Whenever the prefix is self-, ex-, or all-.

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

❌ Don't use a hyphen:

• For predicate adjectives (compound modifiers that come after the word they modify).

• For compounds with an adverb ending in -ly.

Use an en dash:

• When one of the elements in a compound adjective is an open compound (made up of two words with a space between them).

• To indicate a range of numbers, such as inclusive values or dates.

Use em dashes to indicate a break in the flow of a sentence. Don't add spaces around an em dash.

Before using parentheses, consider if you can replace them with dashes, semicolons, or other punctuation marks. If you need to include parentheses, keep the text inside them short.

Use parentheses for abbreviations and acronyms after spelling them out.

In general, try to simplify complex sentences to avoid using semicolons.

Where necessary, use a semicolon to join two closely related independent clauses where a period or a comma is not as effective.

We use American English unless referring to a product, feature, API, or UI element that uses a different flavor of English, like British English.

Outside of technical writing, Elastic has used variations of English in product, feature, and API names. Always use the spelling as it appears in the product when writing documentation.

Similarly, if you are referencing a non-Elastic product that uses a different flavor of English, including in the UI text, use the spelling as it appears in the product.

For example, in the CI/CD observability guide, we use the word "Visualisation" because that's how it appears in the Jenkins UI. Typically we would use the American spelling, "Visualization", instead.

American English is a version of the English language used in the United States. It's sometimes called United States English or U.S. English.

Certain words are spelled differently in American English and British English. You'll find some of these key spelling differences in the following sections.

In American English, verbs that end with -ize usually end with -ise in British English. Similarly, verbs that end with -yze in American English usually end with -yse in British English.

In American English, nouns that end with -or usually end with -our in British English.

In American English, nouns that end with -ense usually end with -ence in British English.

In American English, nouns that end with -og usually end with -ogue in British English.

Follow the standard capitalization rules for American English. In general, use sentence-style capitalization and follow these rules:

• Capitalize the first word of a sentence, heading, title, or standalone phrase.
• Capitalize proper nouns and product names.
• Use lowercase for everything else.
• Match the capitalization as it appears in the UI.

❌ Don't capitalize the spelled-out form of an acronym unless it's a proper noun or is conventionally capitalized.

❌ Don't capitalize API names.

In general, spell out abbreviations when a term is unlikely to be familiar to the audience, or may be familiar only to a specific group of readers. Spell them out the first time you use them in body text—avoid using them in titles. Use the abbreviation rather than the full term for later mentions on the same page.

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.

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.

When making them plural, treat abbreviations as regular words. Do not use an apostrophe before the -s suffix.

If the abbreviation ends in -s, -sh, -ch, or -x, then add -es.

The article (a or an) you use in front of an abbreviation depends on how the abbreviation is pronounced, not how it's spelled.

Avoid Latin abbreviations for common English phrases, unless space is limited.

For more examples, refer to Word choice

For a list of terms and abbreviations commonly used in our docs, refer to the Glossary.