Style

Don’t use the ampersand character in place of and in general text, unless space is limited.

One common issue is whether to repeat articles in lists of two or more items.
In general, you can leave the second and subsequent articles out.

However, there are some cases where it might be better to include the articles:

The * character is called an asterisk.
Don’t use the term star.

The symbol @ is called the at character.

This comes from traditional accounting notation where the cost of multiple items at a specific cost would be given as, for example, 10 apples @ 5 cents = 50 cents, which would be read as 10 apples at 5 cents equals 50 cents.

The "\" character is called backslash.

The { and } characters are called braces.

The [ and ] characters are called brackets or square brackets.

For the ( and ) characters, see parentheses.

The ^ symbol is called a caret.

Avoid using colloquial expressions in Vaadin technical documentation, as they may be unfamiliar to people whose native language isn’t English.

Avoid congratulating the reader, for example, for successfully working through a tutorial and completing the process that the tutorial describes. It sounds patronizing.

Be aware that users of our documentation come from many different cultures. Hence, avoid making references that depend on familiarity with any particular culture.

Avoid using exclamation marks in technical documentation, unless it’s as part of some code syntax. Its use in normal text is distracting and detracts from the professional tone. For example:

Avoid using the future tense to describe the expected behavior of something. Instead, use the present tense. For example:

Always use comma after an introductory clause, phrase, or word.

Avoid using jargon. Always try to use inclusive language.

Don’t use the following Latin abbreviations, but rather write them in English:

Write out names of months in full, if space allows. If you need to abbreviate month names, use the following abbreviations:

Don’t add a period to the abbreviated names.

In text in general, integers between 0 and 9 (inclusive) should be written in words, while other numbers should be written as numerals. Try to avoid beginning a sentence with numerals. For example:

However, in certain contexts, it may be preferable to write all numbers in numerals. Such a context might be, for example, statistical or mathematical content, or where units are specified (such as degrees, metres, or kilograms). For example:

Similarly, use numerals for

For a decimal number greater than –1 and less than 1, put an explicit 0 before the decimal point. For example:

Avoid using Roman numerals (for example, I, IV, vii, ix).

Write out a number if it’s an approximation, rather than an accurate figure. For example:

Write out ordinal numbers (first, second, third, etc.) in full. Don’t use 1st, 2nd, 3rd, etc.

When explaining or describing things that occur in some kind of list or sequence, try to use the same, or equivalent, language structures or terminology to talk about each item in the list. For example, consider the following structure that describes a list of things:

The reader can more easily see the logical structure of the description in this improved version:

The ( and ) characters are known as parentheses.
Use them sparingly.

Consider whether you could achieve the same effect by using commas as delimiters.
As always, the guiding principle is simplicity, and clarity for the reader.

Using the passive too much can have the effect of making our language sound excessively formal.

Accordingly, avoid using the passive when it’s possible to express the same idea elegantly and simply in active voice.

Use the required numeral and the percent sign ("%") with no space between them. If the percentage begins the sentence, write the percentage expression in words. For example:

Don’t use s in parentheses to indicate that there may be one or more of something. == For example

This usage can be confusing for the reader. Instead, choose an alternative wording, even if it’s slightly longer. For example:

Don’t use plus as a synonym for and.

English has two main ways of forming a possessive: the apostrophe and the preposition of.

In general, use the apostrophe for people and animals. For example:

Use the preposition of for things and ideas. For example:

A third possibility is to use one noun as a descriptor of another. For example:

Notice that, in the last group of examples, the noun that’s used as a descriptor is always singular, even if the word it governs is plural. For example:

See also nouns as descriptors; apostrophe.

Product names, such as List Box, should be capitalized in the same way as proper nouns, and not as class names.
A class name can be used if specifically referring to a class; for example, [classname]`ListBox` extends [classname]`ListBoxBase` .

A proper noun is a word or phrase that’s the name of something or somebody; for example, Chrysler Building, Czech Republic, Indian Ocean, Pink Floyd, Windows 11.

It’s distinct from a common noun, which is the "standard" type of noun that identifies the nature of something or somebody; for example, a building, a republic, an ocean, a band, an operating system.

Proper nouns are usually denoted by being capitalized. There are a small number of exceptions to this, usually by the choice of the person or organization that "owns" the name; for example, macOS. In these cases, we should try to use the "official" styling. If you aren’t sure of the correct form, an internet search is usually enough to find it.

Scanning is the process by which a reader quickly overviews the text to evaluate the content. The reader does this to find out whether it really does contain the information that they are looking for. If it does contain that information, they often also want to go directly to the most relevant part of the text.

We can make that process easier by making the core of each point as easy to find as possible. That means putting it near the beginning of the paragraph in which it appears.

We can also make sure that each new point appears in a new paragraph. This also helps the process of scanning.

Consider the following text:

This is good, but we could improve it by moving the most important points to a position near the beginning, and simplifying the language a little, as follows:

We need to avoid slang for two good reasons. One reason is that it detracts from the professional style that we’re trying to convey with our documentation. The other reason is that non-native speakers may not be familiar with slang terms. That would impact the accessibility of our documentation.

The slash character is often used to indicate one or more possibilities from a group. The slash character should be preceded and followed by a non-breaking space. For example:

Try to avoid excessive use of the slash character, particularly when the words and or or would suffice. For example:

Avoid using slashes in abbreviations. For example:

Don’t use the slash character to write fractions, such as 1/2 or 3/4, as these may be liable to misinterpretation.

Instead, use the ½ (½ or ½ in AsciiDoc), ¼ (¼), or ¾ (¾) characters, if appropriate. If the required character isn’t available, use a decimal or spell it out. For example:

Although split infinitives are generally considered to be acceptable these days, it’s worth considering whether you could easily write your sentence to avoid it.

However, there may be some cases where strictly imposing the ideal of avoiding split infinitives could result in an awkward sentence or even introduce ambiguity. Clearly, we always need to prioritize simplicity, clarity, and accuracy, even if it means we have to compromise on elegance.

The character "_" is called the underscore character. You can avoid formatting problems in AsciiDoc by using the _ entity reference.

A space should be inserted between the numeric quantity and the units. Abbreviated forms of units are written in the singular. For example:

The following are the standard abbreviations for common units:

It’s very common to use a compound expression with a numeric value and units as a descriptive phrase. In such cases, use a hyphen to join the compound expression. Notice that the singular form of the unit is always used. For example:

Don’t use Vaadin 14 or other Vaadin version numbers in text. Instead, use the [role="since:com.vaadin:vaadin@V19"] tag to indicate version numbers.

Don’t use the character x as a multiplication sign. Instead, use the multiplication symbol × (× in AsciiDoc).

3F7413BE-4CA8-4D13-A48F-813A00DCB6DB