Style Guidelines for Vaadin Documentation

    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.

    Show code

    AsciiDoc

    Expand code

    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.

    Emphasis Styles

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

    Method Names

    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:

    Warning
    Do not overuse admonitions
    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 tag to indicate versions.

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

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

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

    Plurals

    Articles

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

    Please refer to:

    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.

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

    • : Your Dictionary

    Prefer Active Voice

    You should prefer active voice in writing.

    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