Grammar

abbreviations

Do not terminate abbreviations with a period if the last letter of the unabbreviated form is included in the abbreviation. For example:

Mr Smith
Mrs Smith
Ms Smith
Prof. Smith
Dr Smith
St Petersburg
Microsoft Corp.
M. Duval [abbreviation of the French word monsieur]
and so on.

In general, plurals of abbreviations are formed by adding a lowercase s. Do not use apostrophe s (’s) for this purpose.
For example:

SOPs
[abbreviation for standard operating procedures; not SOP’s]

APIs
[Not API’s.]

admonitions

Admonition blocks such as [NOTE], [TIP], or [WARNING] can be used to emphasize important issues. However, do not overuse them, as this can interfere with the flow of the text .
There should be no more than three admonitions on a page.

Use a descriptive title for admonitions.
For example:

.Do not overuse admonitions
[WARNING]
Overusing admonition blocks interrupts the flow.
Warning
Do not overuse admonitions
Overusing admonition blocks interrupts the flow.

adverb phrases

If you begin a sentence with an adverb phrase, place a comma after the phrase.
For example:

Unfortunately, we cannot reproduce the bug.
As you can see, the screen layout is logical.
This morning, I spoke to our customer services manager.

ampersand ("&")

Do not use the ampersand character in place of and in general text, unless space is limited.

angle brackets

In general text,the name for the < and > characters is angle brackets.
In other contexts, the same characters are known as the less than and greater than symbols.

apostrophe (’)

The apostrophe has a specific function: to indicate when one or more letters have been omitted. For that reason, it is used in contracted forms of verbs.

In general, in our technical documentation, we avoid using contracted forms. They are correct English, but they are more appropriate to less formal writing.

Nevertheless, to show the function of the apostrophe in contractions in general, here are some examples:

I amI’m
[The letter a is omitted.]

She isShe’s
[The letter i is omitted.]

They are notThey aren’t
[The letter o is omitted.]

In some cases this logical system of contraction has been adapted, by convention and usage. For example:

He will notHe won’t
[A little illogical, but it is the accepted contraction.]

We shall notWe shan’t
[And not, for example, sha’n’t.]

The other standard use of the apostrophe in English is to indicate possession.

In fact, this has its logic. In Old English, the possessive case of a noun was formed by adding -es to it.

In modern English, the e has been dropped from that suffix; this omission is now marked by that apostrophe.

The possessive form of a single noun is formed by adding ’s. For example:

The developer’s guide

The boss’s office

The possessive of a plural is formed by the following process:

  • write the ordinary plural form

  • if that plural form already ends in s (the commonest case), place the apostrophe after that s

  • in the few irregular cases where the plural form does not end in s (for example, men, women, children, sheep), add ’s, as for a single noun

For example:

The employees’ salaries
The bosses’ salaries
The women’s records
The mice’s tails

For when to form a possessive using an apostrophe, and when to use of, see possessive.

apposition

Consider this sentence:

The CEO, Nick Smith, spoke to a company employee.

In this sentence, The CEO and Nick Smith identify the same entity (in this case, a person). In other words, Nick Smith is another name for the CEO.

In the terminology, the phrase Nick Smith is "in apposition" with the CEO.
Notice that the phrase that is in apposition is delimited by commas.

Now, consider this sentence:

The CEO, Nick Smith, spoke to company employee Susan Rae.

In this case, company employee and Susan Rae do not identify the same entity.
It is likely that there is only one Susan Rae in this context, but there are, no doubt, many company employees. In other words, Susan Rae is not another name for company employee.

Hence, Susan Rae is not in apposition with company employee and, for that reason, is not delimited by commas here.

Let’s look at an example that is more relevant to the context of technical documentation.
Here is some information about the parameters of a method.

The method takes a single parameter: duration.
The method’s parameter, duration, specifies the time in milliseconds that the animation should run.

Here, as there is only one parameter, the method’s parameter and duration refer to the same entity. Duration is in apposition with the method’s parameter, and so is delimited by commas.

Now, here is some similar information but, this time, the method takes more than one parameter.

The method takes two parameters: startTime and duration.

The parameter duration specifies the time in milliseconds that the animation should run.

Here, parameter and duration do not mean the same thing. For this reason, duration is not in apposition with parameters, so it is not delimited by commas.

articles

Missing and misused articles (a, an, the) are a very common problem, especially for speakers of languages which do not have articles, such as Finnish, Russian, and Japanese.

Although the basic concept of articles is quite simple, there are some special cases and exceptions that can complicate the issue. You may find the following useful:

asterisk

The * character is called an asterisk.
Do not use the term star.

at

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.

author

In some articles, it may be necessary to show the author.
Authors can identify themselves after the section title as follows:

 [.author]
 [name]#Marko Gr&ouml;nroos# <magi@vaadin.com>

For section, this should be in the overview.

Note that for non-ASCII characters, you should use HTML character entity markup.

backslash

The "\" character is called backslash.

braces

The { and } characters are called braces.

brackets

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

For the ( and ) characters, see parentheses.

capitalization

We should capitalize only when there is a good reason for doing so. Otherwise, capitalization can creep into lots of areas where it has no place.

One situation where this often happens is in the context of common abbreviations and acronyms.
We might think that, because capital letters are used in an acronym, we should also use capital letters when the term is written out in full.
This is usually not the case, unless the term is a proper noun. (See proper nouns.)

AbbreviationFull expression

CLI

command line interface

MFA

multi-factor authentication

SaaS

software as a service

JDK

Java Development Kit [proprietary name]

caret

The ^ symbol is called a caret.

code

colon (“:”)

The function of a colon in a sentence is to signal the beginning of an explanation or a list.
Often, we can think of it as saying, and it is this…​ or and this is what I’m talking about…​.
Some examples of this are:

There can be only one reason he is late: he has missed the flight.
Annabel has three valuable characteristics: she is clever, she is conscientious, and she is honest.
On seeing the results of my work, I felt only one emotion: pride.

A colon is also commonly used to introduce a list, particularly at the end of a sentence.
For example:

The parameter can be of several types: integer, boolean, or string.
Three cities are in the running to stage the next Olympics: Beijing, Chicago, and Melbourne.

A colon should not be used to join two full clauses outside the uses mentioned here.
If you are looking for the right punctuation to join two clauses that have some logical relationship, consider using a semi-colon.
Do not use a comma for this purpose. (See comma splice.)

Vaadin uses US English in its documentation. US usage allows a colon to be followed by a sentence beginning with a capital letter, if that sentence is the first of two or more sentences that are governed by the same colon.

There may be several reasons to learn Esperanto: It is completely regular, so you do not need to learn a lot of exceptions. It is not associated with any specific country, so has no political baggage. Finally, it is just fun to learn.

However, if the colon governs only one sentence, begin the sentence with a lowercase letter:

I can give you one good reason to learn Esperanto: it is fun to learn.

colloquial expressions

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

comma splice

Consider the following (incorrectly punctuated) sentence:

You should never divide by zero, this will cause a runtime error.
[Incorrect]

In this example, we have two complete clauses, as each one has a subject and a finite (full) verb. It is an error to join the two clauses with a comma. This error is often called a comma splice. (Splice means join.)

We have several options to rectify this error. The simplest option is to make each clause a sentence on its own:

You should never divide by zero. This will cause a runtime error.

This solution is grammatically correct. However, it does not show the logical connection between the two clauses. A better option would be to use different punctuation. A semi-colon would serve the purpose:

You should never divide by zero; this will cause a runtime error.

Unlike a comma, a semi-colon can be used to join two complete clauses. Moreover, it implies a logical connection between them, although the specific logic is left to the reader’s interpretation. (See semi-colon.)

Another option would be to use an appropriate conjunction. As its name suggests, a conjunction is a joining word. Some common conjunctions are: and, but, or, because, as and so. Conjunctions often imply some kind of logical connection between the clauses that they join.

In our example, we want to express a concept of causation. Because and as would be suitable options:

You should never divide by zero, because this will cause a runtime error.
You should never divide by zero, as this will cause a runtime error.

Although the meaning of these two versions is the same, in fact, by convention, we use as more often than because to express this kind of causation. Consequently, the second version is the best of the options that we have discussed.

commas

There are a small number of situations where commas are mandatory in English. These include:

conditional

congratulations

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

contractions

Contractions (or "contracted verb forms") are those where one or more letters are omitted. For example:

She’s on her way to the meeting. [She’s is a contraction of she is.]

They’ll be here on Friday. [They’ll is a contraction of they will.]

In general use, contractions are perfectly acceptable and correct. In fact, using contractions can help to make a non-native speaker’s English sound much more natural.

However, contractions are not generally appropriate in formal contexts, such as academic works and legal documents. We have made the decision not to use contractions in our technical documentation, perhaps sacrificing a little friendliness of tone in the interests of simplicity of language.

control-key combinations

If your audience includes macOS users, provide the appropriate key-naming terminology. Spell out Control and Command, rather than abbreviating them. For example:

Press Control+S (Command+S on Macintosh) to save.

countable (and uncountable) entities

Some entities have the characteristic of existing as separate objects, such that we can count them.
For example, books are objects that exist separately from each other, so that it makes sense to talk about one book, two books, and so on.
We call this category of objects countable.

We view some other entities as existing in bulk, as amounts of something, rather than a number of separate objects that we can count.
For example, we apply the label air to a contiguous body of gaseous substances. It does not usually make sense to talk about one air or two airs.
The same applies to entities such as sugar, water and aluminum.
We call this category of entities uncountable.

From the point of view of grammar, it is important to consider whether or not some entity is countable.
For example, the indefinite articles, a and an, convey the meaning of one of something.
Hence, it makes sense to use them with countable nouns, but not with uncountable ones.
There is no meaning in the phrases an air or a water.

Similarly, countable nouns, by definition, can be plural.
Uncountable nouns, again by definition, cannot be plural.

However, there is a small trap here.
Many nouns cannot be categorically defined as either countable or uncountable; it depends on their meaning in the given context.

For example, time as a concept is uncountable.
It would not make sense to say, for example:

I’m sorry I haven’t got a time to talk to you now.

On the other hand, time is countable when it means an occasion or a period.
For example:

I remember a time when 1 Mbyte was a lot of memory.
How many times have I asked you not to do that?

Consider, too, the difference between:

I don’t like coffee.
and
Would you like a coffee?
How many coffees have you had this morning?

cultural references

currency

Place currency symbols before the numeric amount. For example:

$25.50

€3

¥45.00

In general, in the absence of other information, we assume that the dollar ($) symbol indicates US dollars. It is not necessary to specify this.

However, where it is required to distinguish between dollar currencies of different states, it should be written as in the following examples:

US$4.50

AUS$19.10

CA$200

HK$99.99

There is no hard-and-fast rule for forming country codes in this context. Just make sure that it is clear which country is being referred to.

dangling participles

Participles are formed from verbs. Present participles end in -ing; past participles often end in -ed, though there are many irregular forms. Some examples:

infinitive

present participle

past participle

to bring

bringing

brought

to have

having

had

to lead

leading

led

to walk

walking

walked

to write

writing

written

Participles are often used as convenient concise forms. For example:

Being the project leader, Hannah Jones chaired the meeting. [A more concise form of: As she is the project leader, Hannah Jones chaired the meeting.]

I was given a spec written on the back of an envelope. [An alternative form of: I was given a spec that was written on the back of an envelope.]

Having caught a terrible cold, I phoned my colleagues to postpone the meeting. [In other words: As I had caught a terrible cold, I postponed the meeting.]

Participles can work well when used in this way, but we need to be careful that our sentence is unambiguous. Consider the last example again:

Having caught a terrible cold, I phoned my colleagues to postpone the meeting.

Who had caught the cold? Was it me or was it my colleagues? Clearly, it was me, but how do we know this? We know because we assume that the next noun phrase after the participle clause indicates the person or thing that the participle refers to.

Look at these similar sentences:

Being corrupt, the file was rejected. [Since the next noun phrase after the participle phrase is the file, it is clear that it is the file that is corrupt.]

Being corrupt, I rejected the file. [In this case, basing our understanding purely on the word order, we might interpret this to mean that I am the one who is corrupt.]

In most cases of such poorly chosen word order, we can probably guess at the intended meaning. However, our goal is that our readers should correctly interpret our material on the first reading.

When the structure of the sentence leaves it unclear to whom or what the participle refers, this is called a "dangling" or "unrelated" participle.

Here are some other examples of poorly chosen, and hence distracting, word order, with some suggestions for improvement:

"Dangling participle" version

Improved version

Being a public holiday, the office was closed.

As it was a public holiday, the office was closed.

Having crashed three times in one week, we decided to replace the server.

As the server had crashed three times in one week, we decided to replace it.

dash (“–”)

dates

In our documentation, we use the format <month> <day number>, <year>. We do not use the ordinal abbreviation suffixes -st, -nd, -rd or -th. Nor do we write the word the between the month name and the day number. For example:

June 15, 2020

May 1, 2022

Avoid expressing dates using variations of the mm/dd/yyyy or dd/mm/yyyy formats. There are different conventions for these formats around the world, so that the possibility of confusion and misunderstanding is high. Instead, write out dates using month names, as described earlier.

days

Write out the days of the week in full, if space allows this. Otherwise, abbreviate the names to three characters, as follows:

Day3-letter abbreviation2-letter abbreviation

Sunday

Sun

Su

Monday

Mon

Mo

Tuesday

Tue

Tu

Wednesday

Wed

We

Thursday

Thu

Th

Friday

Fri

Fr

Saturday

Sat

Sa

definite article (“the”)

double quotes (“)

See “quotation marks”

em dash ("—")

In US English, a pair of em dashes (so called because they have the same width as the letter M) are used to indicate a fragment of text in parenthesis. The pair of em dashes imply a more significant break in the structure of the sentence than one marked by a comma or brackets. There should be no space either before or after an em dash. For example:

The tool does not fix the bug—if only it were that simple—but it does help you to identify its location.

You can use a dropdown or a combo—personally, I prefer the latter—but, either way, the user needs to be able to select from the available options.

A single em dash can be used to add an afterthought or aside. For example:

You can use whichever IDE you prefer—it is entirely up to you.

Make sure your code is well commented—you will thank yourself when you revisit it six months later.

Avoid using the em dash too much; it can quickly become distracting and even irritating. Very often, a comma or semi-colon is a more appropriate choice of punctuation, especially in more formal writing, such as technical documentation. The two previous examples could also be written as:

You can use whichever IDE you prefer; it is entirely up to you.

Make sure your code is well commented; you will thank yourself when you revisit it six months later.

emphasis

Use the emphasis styles, such as [classname]#ClassName# emphasis for class names and [methodname]#methodName()# for methods.

Table 1. Custom emphasis styles
Style ElementAsciiDoc Example CodeResult

Class Names

[classname]#Component#

Component

Interface Names

[interfacename]#EventListener#

EventListener

Method Names

[methodname]#setValue()#

setValue()

GUI Buttons

[guibutton]#OK#

OK

GUI Labels

[guilabel]#OK#

OK

File Names

[filename]#readme.txt#

readme.txt

Other Monospace

`appName`

appName

Key Caps

kbd:[Ctrl + C]

Ctrl+C

Menu Choices

"Help > Updates" or menu:Help[Updates]

Help  Updates

en dash ("–")

The en dash (so called because it has the same width as the letter N) is commonly used to indicate a range of values. When used in this way, it is not preceded or followed by a space. For example:

Select a number in the range 0–255.

The parameter should be a string of 8–10 characters.

The licence enables you to use the software on 1–3 computers.

He was chief designer (2003–9), and subsequently CEO of the company (2009–12).

The office is open Monday–Friday.

We can also describe ranges by using the words from and between. These forms should not be mixed with the en dash. Use one form or the other, but not both. For example:

You can use the licence on between 1 and 3 workstations.
[Not between 1–3 workstations.]

The parameter should be a string of from 8 to 10 characters.
[Not a string of from 8–10 characters.]

euro

The euro symbol (€) is represented as &euro; in AsciiDoc. In amounts of money, place the euro symbol immediately before the numeric quantity, in the same way as for, for example, the dollar or pound symbol.

exclamation mark ("!")

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

You have now created your component! [Avoid this usage.]

#!/bin/bash [The exclamation mark is part of the script syntax.]

future tense

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

When the compilation is complete, the program displays summary information. Not will display.

Run the code in debug mode. Execution pauses at the breakpoint that you have specified. Not will pause.

headings

You should use title or headline case for all headings and chapter, section, or sub-section titles.

= Style Guidelines for Vaadin Documentation

For a detailed description of capitalization rules, see for example:

hyphen (“-”)

There is often confusion about whether or not to use a hyphen in compound words (such as start-up and onboarding) and words that include a prefix (such as presales and multifactor). English has no hard-and-fast rules about this; it is simply a question of accepted usage.

In general, use the Merriam-Webster online dictionary as a guide. If the full compound word or prefixed word exists in the dictionary, use the form that the dictionary gives. If the full compound word or prefixed word does not exist in the dictionary, use a hyphen. For example:

start-up (noun)
[This is the form given in the dictionary.]

setup (noun)
[This is the form given in the dictionary.]

log-in (noun) [Neither log-in nor login is given in the dictionary, so use a hyphen.]

Sometimes, we want to mention a series of items, all hyphenated on the same base word. In such cases, we can reduce repetition by applying distributed hyphenated descriptive words to the base word. For example:

The device used a combination of first-generation and second-generation chips.
[OK, but repetitive.]

The device used a combination of first- and second-generation chips.
[Better.]

In general, use a hyphen in compounds formed from an adverb and an adjective, in order to avoid ambiguity as to which word the adverb qualifies. For example:

I am grateful to my hard-working colleagues. Not hard working colleagues.

This benefits low-paid employees. Not low paid employees.

However, do not use a hyphen when the adverb ends in -ly. In these cases, there is no ambiguity concerning which word the adverb applies to. For example:

The technology is a closely guarded secret. Not closely-guarded secret.

This benefits poorly paid employees. Not poorly-paid employees.

indefinite article

introduction

introductory clauses

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

After a while, you can look into it.

Nevertheless, fields are components.

Meanwhile, you can use a workaround.

Additionally, we need to make the call to the REST service.

jargon

Avoid using jargon. Try to use inclusive language at all times.

Latin abbreviations

lists

An inline list should be introduced by a colon. Items in the list can be separated by commas. However, in cases where items in the list themselves contain commas, it is better to use semi-colons as separators, in order to avoid confusion. For example:

This curry has three vital ingredients: onion, potato, and spinach.

This curry has three vital ingredients: onion, which should be roughly chopped; potato, which should be diced; and fresh spinach leaves, which should be thoroughly washed before use.

If an AsciiDoc file is intended to be rendered as a section, a page, or tab, it must have a header block. This is used to build the menu in the documentation website.

---
title: Title of the article
order: 4
layout: page
---
title

The title to be displayed in the menu. The title should be same as the title of the article, but can be a shortened version to keep the menu more tidy.

order

Order number in the menu. If articles are reorganized, the order numbers may need to be reorganized, too. It is good practice to make them multiples of 10 or 100, in order to leave space to add new articles without having to renumber all the others.

layout

The layout can be either page or tabbed-page. In a tabbed page, the sub-articles are displayed in tabs rather than in the menu. The default tab content comes from the index.asciidoc.

tab-title

Sets the tab title in tabbed-page pages. It should be kept short.

method names

Use empty parentheses at the end of method names to denote that they are methods. In general, do not list parameter types for methods, unless this is required in order to indicate a specific version of a method. It may also be necessary to specify a parameter when it is relevant in the context. For example:

Call setEnabled(false) to disable it.

months

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

MonthAbbreviation

January

Jan

February

Feb

March

Mar

April

Apr

May

May

June

Jun

July

Jul

August

Aug

September

Sep

October

Oct

November

Nov

December

Dec

Do not add a period to the abbreviated names.

multiplication sign

If you need to show the multiplication sign, use × (&times;), not the letter x. One case for using the multiplication sign is to refer to dimensions. There should be a non-breaking space on either side of the multiplication sign. For example:

The image size should be at least 150 × 150 pixels.
[That is, 150&nbsp;&times;&nbsp;150 pixels.]

In code, you obviously need to use the symbol that is required by the language you are using, which is generally the asterisk character (*).

non-breaking space

Use a non-breaking space to prevent the browser from splitting terms in a way that could cause confusion for the reader. Some examples are:

  • between a number and its units

  • between numbers and words that define a date

  • between a person’s title (Ms, Dr, Prof.) and their name

  • between words separated by a slash ("/") character

A non-breaking space can be written in AsciiDoc as &nbsp;.

nouns as descriptors

English is very versatile in allowing nouns to be used as if they were adjectives. For example:

Please close the office door quietly.

Select your preferred keyboard layout.

Bear in mind that when nouns are used like adjectives in this way, they are almost always used in the singular form, not plural. For example:

She is the manager of a shoe shop. [Not a shoes shop.]

This is the responsibility of the microchip manufacturer. [Not the microchips manufacturer.]

number sign

Do not use the # character to indicate a number. For example:

See item #3. *[Instead, write See item number 3.]

numbers

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:

The team consisted of one team leader, two senior programmers, and 10 junior programmers.

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:

In a survey, 7 out of 10 developers said that they preferred Python to Perl.

You can calculate the value using 2 * π * r.

The sample was found to have expanded by 6 mm at the end of the experiment.

Similarly, use numerals for

  • page numbers

  • version numbers

  • numbers in a technical context, such as size of memory, processor speed, file sizes, etc.

  • percentages

  • negative numbers

  • decimal numbers

  • ranges of numbers

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

0.5 [Not .5]

-0.02 [Not -.02]

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

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

There must have been a thousand people at the meeting.
[Not There must have been 1,000 people….]

You had to write hundreds of lines of code.
[Not You had to write 100s of lines of code.]

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

Oxford comma

See “lists”.

parentheses

passive voice

percentages

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:

In 99% of cases, the methodology works.

Ten percent of hacking attempts succeeded.

phrasal verbs

plurals

Do not use s in parentheses to indicate that there may be one or more of something. == For example

Inspect the error message[line-through](s) for more detailed information. [Avoid this form of optional plural.]

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

Inspect any error messages for more detailed information.

plus

Do not use plus as a synonym for and.

possessive

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:

The team leader’s keyboardA manager’s salaryThe employees' well-beingThe horse’s mouth

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

the name of the methodthe beginning of the processthe keyboard of the computerthe door of the office

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

the method namethe computer keyboardthe office door

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

the method namesthe computer keyboardsthe office doors

procedures

In technical documentation, we very often want to describe the procedures that are necessary in order to perform some task. Such procedures usually consist of a series of steps.

In most cases, we start with a top-level sentence. For example:

Create a new project as follows:

To create a new project, follow these steps:

Do not start with an incomplete sentence at the top-level which is then completed by the text of each step. This structure obliges the reader to keep the top-level text in mind in order to interpret the subsequent text correctly. For example:

To create a new project, you must:
[Avoid beginning with an incomplete sentence which is completed by the text of subsequent steps.]

Log in…

Make sure you have installed the plugin…

Create a new app…

Use parallel structures in the steps that make up the procedure. In other words, structure each step in a similar way to the others.

product names

Product names, such as List Box, should be capitalized as is usual for proper nouns, not as if they were class names. Use the class name if you are referring specifically to a class. For example:

ListBox extends ListBoxBase.

However, do not use class names in component documentation, which should be language-independent; that is, neither Java- nor JavaScript-specific.

proper nouns

punctuation

See the specific entries for each punctuation mark; for example, “commas”, “quotation marks”, etc.

quotation marks

In general, when you want to put text in quotation marks, use double quotation marks (" "). Avoid using single quotation marks (' '), unless, of course, it is required by some code syntax.

relative clauses

Relative clauses allow us to give more information about a person or thing that we mention in a sentence. For example:

Instead of saying: I asked Linda Johnson. She works in the same office as me,

it is neater to say: I asked Linda Johnson, who works in the same office as me.

They are called "relative clauses" because they relate to some entity in the main clause of our sentence. The word that links the relative clause to the main clause is often a "W" word, such as which, who, where, when, or whose. The word that is also often used as the linking word. For example:

The software is written in Java, which is our preferred language.

Jean Reboulet, who led the design team, attended the meeting.

The conference was held in San Francisco, where the company has its headquarters.

We recommend performing full backups at the weekend, when the system is less busy.

We contacted Sandra Stein, whose team maintains the library.

This is the team that maintains the library.

We need to be aware that there are two kinds of relative clause: defining and non-defining.

Why is this important? It matters because it has an impact on the punctuation we need to use, and also on the sentence structure.

A defining relative clause, as the name suggests, defines an entity in the main clause. It gives us essential information in order to identify the person or thing that was mentioned. In other words, without the information in this clause, our sentence would not have the same meaning and might not even make sense at all. For example:

This is the bug which our testing team reported.
[The relative clause is essential in order to understand which bug is being talked about.]

The place where you parked your car is private property.
[The relative clause identifies the place that was mentioned.]

screenshots

Every page should have at least one screenshot. There should at least be a screenshot in an introduction or overview section.

section

The basic structure of a new section file is as follows:

---
title: Title of the section
order: 4
layout: page
---

[[thechapter.thefeature]]
= Fine Feature

[.author]
[name]#Marko Gr&ouml;nroos# <magi@vaadin.com>

The Fine Feature is a feature of a feature...

[[thechapter.thefeature.basic-use]]
== Basic Use

semi-colon (“;”)

single quotes (‘ ’)

See “quotation marks”.

slang

We need to avoid slang for two good reasons. One reason is that it detracts from the professional style that we are 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.

slash (“/”)

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:

The library contains routines to facilitate input / output.

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

I was responsible for bug-fixing and maintenance work. [Not bug-fixing / maintenance work.]

Please get back to me if you have any questions or queries. [Not if you have any questions / queries.]

Avoid using slashes in abbreviations. For example:

in charge [Not i/c.]

AC-DC [Not AC/DC, unless in the context of Australian rock groups.]

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

Instead, use the ½ (&frac12; or &half; in AsciiDoc), ¼ (&frac14;), or ¾ (&frac34;) characters, if appropriate. If the required character is not available, use a decimal or spell it out. For example:

The inverse of 8 is one-eighth.

The inverse of 8 is 0.125.

split infinitive

The infinitive of a verb is the form that includes the particle "to". Examples of infinitives are to have, to hold, and to program.

Traditionally, it was considered bad style to "split" the infinitive by placing an adverb between the particle and the verb. For example:

It is necessary to fully understand the process before starting. [Instead of, for example, to understand the process fully.]

We had to completely rebuild the library. [Instead of, for example, to rebuild the library completely.]

Although split infinitives are generally considered to be acceptable these days, it is worth considering whether you could easily write your sentence so as 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 need to prioritise simplicity, clarity, and accuracy at all times, even if it means we have to compromise on elegance.

time

Use the ratio character ("∶", &ratio;) as the delimiter in times, rather than a standard colon. The difference is that the ratio character is vertically centered on the line, whereas the colon character is anchored to the baseline. For example:

The seminar begins at 11∶00 UTC.
[Not 11:00 UTC.]

time clauses in the future

We often use time clauses to refer to some time in the future. Such clauses may begin with when, while, until, as soon as, before, and after. In English, we generally use a present or present perfect tense in this type of clause, in spite of the fact that it refers to a future time. The remainder of the sentence may use any appropriate future form, or an imperative (instruction) form. For example:

As soon as you get to the office, call me. [Not As soon as you will get…]

While I am in Scotland, I’ll visit Edinburgh Castle. [Not While I will be in Scotland…]

When you have finished that work, you can start the next task. [Not When you will finish… or When you will have finished…]

underscore

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

units

There is a space between the numeric quantity and the units. Abbreviated forms of units are written in the singular. For example:

The maximum permissible weight is 28 lb. [Not 28 lbs.]

The following are the standard abbreviations for common units:

unit

abbreviation

degree

° (no space)

feet

ft

gigabyte

GB

gram

g

hour

h

inch

in

kilobyte

kB

kilowatt

kW

litre

l

megabit

Mbit

megabyte

MB

megawatt

MW

metre

m

millimetre

mm

minute

min

ounce

oz

pound (weight)

lb

second

s

terabyte

TB

It is 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:

A 22-page book. [Not A 22-pages book.]

A twenty-mile journey. [Not A twenty-miles journey.]

A 25,000-ton ship. [Not A 25,000-tons ship.]

Vaadin versions

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

x

Do not use the character x as a multiplication sign. Instead, use the multiplication symbol × (&times; in AsciiDoc).