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.
Vaadin documentation should follow the following conventions for AsciiDoc source files.
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.
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.
Always use the emphasis styles, such as
[classname]#ClassName# emphasis for class names and
[methodname]#methodName()# for methods.
|Style Element||AsciiDoc Example Code||Result|
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:
setEnabled(false) to disable it.
Admonition blocks such as
[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.
.Do not overuse admonitions [WARNING] Overusing admonition blocks makes text restless.
Do not overuse admonitionsOverusing admonition blocks makes text restless.
Every page should have at least one screenshot. There should be one at least in an introduction or overview.
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.
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).
You can use the following items:
It should now look as follows:
Avoid using the word like and other similar words.
Do not use contractions, such as don’t or we’re.
Do not write contractions, we are very particular about that.
Do not use the following Latin abbreviations, but rather write them in English:
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.
Rather use "that is", surrounded with commas.
The parameter is the class name of the widget set, that is, without the extension.
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.
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
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.
Use space key rather than spacekey. (Note that space key is a generic name and should be lower case)
Data is singular, not plural.
Missing articles are a very common problem, especially for Finnish writers.
Please refer to:
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
You should not use rich formatting such as bold, italic, or monospace in headings.
Using the @CssImport Annotation
Contents of the index.html File
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
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).
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.