Style Guidelines for Vaadin Documentation

This article describes various style guidelines for Vaadin documentation. The basic markup instructions is described in Formatting Vaadin Documentation With AsciiDoc.

Many of the guidelines are checked by the Vale linter.

Document Source Conventions

Vaadin documentation should follow the following conventions for AsciiDoc source files.

One Line per Sentence

You should aim to write one line per sentence. AsciiDoc does not care about line breaks, only paragraph breaks. This helps in organizing sentences by moving a single line. For example, in Atom you can do that with Ctrl+Up and Ctrl+Down, and in VS Code with Alt+Up and Alt+Down. You can also more easily delete or comment out a sentence. It also prevents line reflow when editing a single sentence. The convention thus also helps in viewing documentation diffs, etc.

Show code

AsciiDoc

Expand code

You should aim to write one line per sentence.
AsciiDoc does not care about line breaks, only paragraph breaks.
This helps in organizing sentences simply by moving one line.
For example, in Atom you can do that with kbd:[Ctrl+Up] and kbd:[Ctrl+Down], and in VS Code with kbd:[Alt+Up] and kbd:[Alt+Down].
You can also more easily delete or outcomment a sentence.
It also prevents line reflow when editing a single sentence.
The convention thus also helps in viewing documentation diffs, etc.
You should also aim to keep sentences short, to fit one line each.
Shorter sentences make text easier to read.
It is not a big problem if some lines are longer – it is just a guideline.

You should also aim to keep sentences short, to fit one line each. Shorter sentences make text easier to read. It is not a problem if some lines are longer; it is just a guideline.

In Atom, you can press Ctrl+Alt+Q to rewrap the current paragraph or selection.

Formatting Style Guidelines

Emphasis Styles

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

Method Names

Method names should have empty parentheses in the end to denote that they are methods. Parameter types should not be listed for methods, unless it is especially necessary to indicate the specific version of a method. Also, a parameter can be given in cases such as the following:

Call setEnabled(false) to disable it.

Product Names

Product names, such as List Box, should be capitalized like names normally are, and not as class names. Class name can be used if specifically referring to class, such as “ListBox extends ListBoxBase”. That should not, however, be used in component documentation, which should be language agnostic, neither in Java or JavaScript.

Admonitions

Admonition blocks such as [NOTE], [TIP], or [WARNING] can be used to emphasize important matter. They should not, however, be overused or otherwise the text gets restless. There should be no more than 3 admonitions on a page.

Admonitions should always have a descriptive title.

For example:

.Do not overuse admonitions
[WARNING]
Overusing admonition blocks makes text restless.

Taking Screenshots

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

Vaadin Versions

Do not use “Vaadin 14” or other Vaadin version number notes in text. Rather use the [role="since:com.vaadin:vaadin@V19"] tag to indicate versions.

English Language

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.

• Also, let us make the call to the REST service.

Introducing a Listing

You should use the word follows or following to introduce a list or code listing. Examples are introduced with “for example“. The sentence should be ended with a colon (not period).

For example:

For example:

You can use the following items:

It should now look as follows:

Avoid using the word like and other similar words.

Contractions

Do not use contractions, such as don’t or we’re.

Do not write contractions, we are very particular about that.

Latin Abbreviations

Do not use the following Latin abbreviations, but rather write them in English:

e.g.

Rather use expression such as such as, for example, or for instance.

Note that for example always requires surrounding commas, while such as only requires preceding comma when it is used in the beginning of a restrictive clause.

• You may find, for example, JSF or Flash more suitable for such purposes.

• For example, consider that you have the following composite class.

• You may find frameworks such as JSF or Flash more suitable for such purposes.

• Some frameworks, such as JSF or Flash, can be more suitable for such purposes.

i.e.

Rather use “that is“, surrounded with commas.

The parameter is the class name of the widget set, that is, without the extension.

etc.

This abbreviation is sometimes fine to use, but you are nevertheless encouraged to use expressions such as and so forth. If used, it should be preceded by comma and followed by period.

• You would normally implement some views, etc.

• You would normally implement some views, and so forth.

Definitions of Abbreviations

You should define any abbreviations that you use by writing it out and having the abbreviation in parentheses. Commonly known abbreviations do not need to be defined.

• You can use Vaadin with Contexts and Dependency Injection (CDI)

• Please read the FAQ

Commonly known abbreviations are listed in .github/styles/Vaadin/Abbr.yml.

Lists

Lists should begin with a colon (:) after an introductory clause. If there are more than two items, you should use serial comma (or Oxford comma) before the conjunction.

Vaadin has three kinds of components: fields, layouts, and other components.

Usually, if the items require an article (the, a, an), it should only be for the first item, unless emphasis is needed.

Words

• Use space key rather than spacekey. (Note that space key is a generic name and should be lower case)

Plurals

• Data is singular, not plural.

Articles

Missing articles are a very common problem, especially for Finnish writers.

Please refer to:

• Grammarly Handbook about the use of articles (in English)

• Yksikkö, monikko ja artikkelit (in Finnish)

• Articles (in Finnish)

• etc.

Repeating Articles in Lists

One common issue is whether to repeat articles in lists of two or more items. In general, the latter article can be left out if. In the following cases it would be needed:

• There’s some ambiguity: a text field has a caption and input box (the box would also refer to the caption: “caption box“) →

  • A text field has a caption and an input box

  In a similar way, an adjective for an item could cause ambiguity whether it is for the following item or also the next ones: a nested field and layout.

• Need to emphasize the list, or that the items are distinct and each is important:

  • You have two ways: the right way and the wrong way.

  • The Good, the Bad, and the Ugly

Formatting in Headings

You should not use rich formatting such as bold, italic, or monospace in headings.

• Using the @CssImport Annotation

• Contents of the index.html File

Title Case

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

= Style Guidelines for Vaadin Documentation

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

• Rules for Capitalization in Titles of Articles: Your Dictionary

Prefer Active Voice

You should prefer active voice in writing.

Front-End, Front End, or Frontend

We follow the following convention:

• Use frontend rather than front end (noun) and front-end (adjective).

• Use backend rather than back end (noun) and back-end (adjective).

However:

• Use server-side for adjectives such as in “server-side framework.”

• Use server side for nouns such as in “Do it on the server side.”

• Same for client-side.

Other Preferred Terms

• Application over app

• Asynchronous over async

• Overlay over dropdown

• Time frame over timeframe

• Repository over repo

• npm over NPM

• divider over separator