Style Guidelines for Vaadin Documentation
This document briefly describes various style guidelines for Vaadin documentation. The basic markup instructions are given in the AsciiDoc Reference for Vaadin Documentation (PDF).
Document Source Conventions
In the following, we consider some 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 simply by moving one line. For example, in Atom you can do that with Ctrl+Up and Ctrl+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 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]. 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
Always use the emphasis styles, such as
[classname]#ClassName# emphasis for class names and
[methodname]#methodName()# for methods. Note also the other
emphasis styles; they are listed in the AsciiDoc Reference for Vaadin Documentation.
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.
Source code listings should have the file type indicated to enable highlighting.
[source, java] ---- Button button = new Button("OK"); ----
Will show as:
Button button = new Button("OK");
Note that you can not mix source formatting with emphasis, such as the [replaceable] style. Also, XML formats ugly in the print edition, so please do not use source code type for that.
For print edition, code blocks have line length limit of 63 characters. If lines are longer than that, they can wrap very ugly. Please indent lines manually so that they are pretty.
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.
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).
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.
Latin Abbreviations (i.e., e.g., etc.)
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.
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.
There are 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:
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:
There are two ways: the right way and the wrong way.
The Good, the Bad, and the Ugly
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