Style

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:

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

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.

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.

Capitalization

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

= Style Guidelines for Vaadin Documentation

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

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

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

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

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. Different conventions for these formats are used 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

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.

Listings

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

For example:

For example:

You can use the following items:

It should now look as follows:

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.

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 (*).

Number Sign

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

See FAQs #3.
[Instead, write See FAQs number 3.]

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.

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

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