Documentation

Documentation versions (currently viewingVaadin 24)

Documentation Style Guide

Writing style guidelines for documentation writers.

We have certain ways of talking to each other, ways that say plenty about who we are and how we see the world. In our documentation, we want to offer information as clearly as possible. We would also like people to have a favorable impression of us and what we stand for as an organization. Therefore, the documentation must maintain a professional and consistent style.

You can use the Vale linter to help yourself conform to these guidelines. Vale is also used as a part of the GitHub pull request review automation.

Writing Style

You can maintain a professional and consistent voice in several ways. One is to write using the same good voice and tone. Another is to avoid the passive voice and use instead the active voice, as well as writing mostly in the present tense. More fundamental is the choice of language variance. These topics are explained in the sub-sections here.

Voice & Tone

Voice refers to how you say things. Likewise, when explaining something, you should adopt an appropriate tone.

When you write documentation, there are certain things you’ll want to communicate to the reader. But there are many ways you can express that information.

When you write documentation, you’re essentially acting as the public face of the organization. That may sound like a lot of responsibility, but it’s not so difficult. We’re all able to be friendly and helpful — and that’s all that’s required. Write like someone who cares about the reader — which you obviously do if you’re contributing.

"Tone" is more about finding the correct balance between being overly formal and rigid, and being too casual. You can take great care to explain issues thoroughly and thoughtfully. However, if you use language that’s so formal that the material sounds unapproachable, or so informal that it sounds unreliable, you risk losing the reader.

You should be aiming for a professional, friendly tone.

Present Tense

In general, use present tense rather than future tense. It tends to give a fresher feel to the text. In particular, try to avoid using the word will where possible. For example:

When the compilation is complete, the program displays summary information.
When the compilation is complete, the program will display summary information.

Sometimes future tense is unavoidable because you’re actually talking about the future. Attempting to predict the future in a document is usually a bad idea, but sometimes it’s necessary.

However, the fact that the reader will be writing and running code in the future isn’t a good reason alone to use the future tense. Stay with the present tense where possible.

Press OK. A new dialog opens.
Press OK. A new dialog will open.
If there is no authenticated user, the method returns null.
If there is no authenticated user, the method will return null.

American English

The English language basically originated in England. However, there are many variances of English. Given the influence of the United States in the marketplace and with software developers worldwide, we strive to use American English in the documentation. Here are some simple spelling examples:

Customize
Customise
Color
Colour
Behavior
Behaviour

In these examples, the recommended spelling is American English, while those to be avoided are in British English.

Audience

It’s important to have a sense of your audience when writing, to know who will read what you write. This includes deciding on the skill levels to assume about the reader.

Skill Levels

As much as reasonable, try to include people from a wide range of technical abilities. Although Vaadin’s documentation is aimed at an audience that has a certain level of technical awareness, you should be careful not to make too many assumptions about an individual reader’s knowledge and skill set.

While trying to make explanations of technical topics understandable to the lowest skill level of our readers, don’t be condescending. Our readers are generally intelligent people. Along these lines, avoid congratulating the reader. For example, don’t congratulate them for working through a tutorial and completing the process that the tutorial describes:

Well done! You’ve now completed the tutorial, successfully.

At a minimum, this sounds patronizing. More than that, if the reader was unsuccessful or had difficulty with the tutorial, they’ll be particularly irritated by being congratulated or might feel stupid for having problems. Instead, write something like this:

You’ve now completed the tutorial.

Global

Vaadin documentation is provided in English for the benefit of users all around the world. For many of these users, though, English isn’t their native language. For this reason, you’ll need to write in a style that’s as clear and as accessible as possible. The following principles can help you to achieve this goal.

Use Short, Simple Sentences

Consider this example:

Vaadin components do support client-side validation to increase the responsiveness of the application, but the developer should be aware that these should be used purely for convenience since they can be circumvented in the browser.

This could be made more understandable as follows:

Vaadin components support client-side validation to increase the responsiveness of the application. However, as a developer, you’d use this only for convenience, as it’s easy to circumvent client-side validation in the browser.

Here is another example, but in which longer, more complicated sentences can be reduced to shorter, simpler ones:

For instance, if the developer sets a component to be disabled, this effect is set both on the server and the client. On the client, an attacker can circumvent this (attackers have full control over anything in the browser), but the server blocks any interaction with the component, and a warning is printed to the server logs.

This could be improved as follows:

For example, if the developer disables a component, it’s disabled on both the server and the client. An attacker may be able to circumvent this on the client since they have full control over their browser. However, the server blocks any interaction with the disabled component. The server also writes a warning message to the server logs.

Keep the Verb Near the Subject

Try not to separate the subject from the verb with too many words. This can make a sentence difficult to interpret. Consider the following sentence:

Data coming from a data store (such as a database) and inserted as HTML into DOM elements (for example, setting innerHTML for elements or using HTML mode in component captions) should also be escaped.

This could be improved as follows:

If you insert data from a data store into DOM elements as HTML, be sure to escape the data first. This would be necessary, for example, if you were using data from a database to set innerHTML, or using HTML mode in component captions.

Use Only One Verb in a Sentence.

For simplicity and ease of understanding, it’s a good general goal to try to have only one verb in each sentence. However, when there is a strong logical connection between clauses (such as implied by words like “while”, “when”, “because”, “so”, “since” and “although”), it may be better to use multiple verbs in a sentence. Here’s an example of this:

The request isn’t available in background threads, so the isAuthenticated() method shows the authentication state only in Vaadin request processing threads, otherwise, it would always return false.

This could be improved as follows:

The request isn’t available in background threads. Therefore, the isAuthenticated() method shows the authentication state only in Vaadin request processing threads. Otherwise, it returns false.

Inclusiveness & Accessibility

In simple terms, inclusiveness means not excluding people on an arbitrary basis. For instance, you wouldn’t exclude people or readers based on their gender, age, disability, race, religion, or sexual orientation.

It’s important to remember that not everyone reads web pages with the same types of devices and in the same way. For instance, some read the documentation on their telephone or on a tablet, while others on a desktop computer. Some tilt hand-held devices sideways, and some use larger fonts to aid their vision. For this reason, web content needs to be created in a way that’s easily viewable by various devices and accessible for screen readers.

Cultural References

Be aware that users of the documentation come from many different cultures. Hence, avoid making references that depend on familiarity with any particular culture may lose some readers. For instance, providing examples that require an understanding or familiarity with a specific sport or a religious ritual might be confusing to some.

Accessibility

Since some readers are disabled in some way, there are certain ways in which you may tend to write that make the text confusing or the information inaccessible. More than that, documentation that is accessible to all can often benefit all readers.

Directional Language

Avoid using terms like on the left, above, or below to describe the location of something on the screen. These terms aren’t useful and can be confusing for screen readers.

In the previous example.
In the example above.

Graphics & Images

Graphics can be useful as a way of conveying information quickly and succinctly. However, not everyone can see graphics clearly or at all.

For this reason, you should also use alternative ways of communicating the information shown in any given graphic. When using graphics, make sure the reader gets the same information in the text. The graphic should be an enhancement to what you’re saying in the text — not instead of writing text.

== Abbreviations, Punctuation, Etc.

Words over Symbols

In text, spell out words like and, plus, and or, rather than use symbols (i.e., &, +, /). Screen readers may vary in how they interpret such symbols. You can, however, use the ampersand character (i.e., &) in headings and titles to make them shorter and easier to scan. In the same way, unless you’re referring to values, try not to use numbers.

The DOM structure of VerticalLayout and HorizontalLayout was developed to maintain the same set of elements and …
The DOM structure of VerticalLayout & HorizontalLayout.
Voice & Tone (in a heading or a title)
The voice & tone of the documentation is professional and friendly.
The identifier consists of its tag plus a running counter.
The identifier consists of its tag + a running counter.
Login as admin or root before proceeding.
Login as admin/root before proceeding.
The user is allowed only 3 attempts if the variable is set to a value of 3.
The user is allowed only three attempts if the variable is set to a value of 3.

Latin Abbreviations

Don’t use Latin abbreviations like "i.e." and "e.g." in the main text of sentences. Instead, write them in English. Using them inside parenthesis is acceptable when you want to clarify the meaning of a sentence without distracting or diverging the reader too much.

For Example

Rather use expressions like such as, for example, or for instance.

The phrase for example always requires surrounding commas, while such as may only need a preceding comma when it’s used at the beginning of a restrictive clause.

For example:

You may find, for example, JSF or Flash more suitable for such purposes.
You may find, e.g., JSF, or Flash more suitable for such purposes.
For example, consider that you have the following composite class.
E.g., 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.
Due to the way overlays (e.g., Dialog) are rendered in embedded Flow UIs, the utility classes don’t work in them.

That Is

The abbreviation "i.e." means "that is" in Latin. When used in the main text of a sentence, don’t use the Latin abbreviation. Use the English text instead — surrounded with commas.

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

The exception to this is when the text is contained within parentheses. Then it’s optional as to whether to use the Latin abbreviation or the English equivalent. Remember to follow either with a comma, though.

Switches focus between sections of the grid (i.e., header, body, footer).

And So Forth

This Latin abbreviation "etc." in English is basically, "and so on". It’s fine to use it sometimes. However, it’s sometimes better to use expressions such as and so forth. If the Latin abbreviation is used, though, it should be preceded by a comma and followed by a period.

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

Unlike other Latin abbreviations, this one may be used outside a parenthetical comment, in the main text of a sentence.

Excited, Questioning, & Pondering

In the documentation, we shouldn’t indicate that we’re excited, questioning, or pondering. Therefore, the punctuation should not reflect these emotions or states.

Avoid ending a sentence with an exclamation mark. Its use in normal text is distracting and detracts from the professional tone. If you want to sound enthusiastic about the software, or positive in some way, show it in your word choices, not in your punctuation.

Don’t pose a question in the text; don’t end a sentence with a question mark. You’re not in dialog with the reader, so don’t ask them a question when you can’t hear their response. That’s potentially irritating to the reader. Instead, write what you want to say without questions. The exception to posing a question and using a question mark is for titles of troubleshooting articles.

The use of ellipses (i.e., …) at the end of a sentence, usually an incomplete sentence, is meant to indicate that the writer is thinking or calling upon the reader to ponder something. Write complete sentences; write what you want to say. Don’t require the reader to wonder what you’re thinking. Ellipses sometimes can be used in the same way in the middle of a sentence. They’re also sometimes used in lieu of etc. Again, don’t use them.

These three punctuation rules don’t apply to using them as part of some code syntax or code example. They apply only to sentences and headings. Ellipses are sometimes used in code or log examples in place of lengthy, unimportant text. This is an acceptable use.

You’ve now created your component.
You’ve now created your component!
This is important to avoid because it’s a security vulnerability.
Why is it important to avoid this? It’s important because it’s a security vulnerability.
They control how series are displayed (e.g., color, border, opacity, etc.) and similar aspects.
They control how text is displayed (e.g., color, border, opacity, …​) and similar aspects…​

Lists & Oxford Comma

Items in a list can be separated by commas. If a list contains three or more items, and the last item is preceded by a conjunction (i.e., and, or), place a comma before the conjunction. This use of a comma is called the Oxford comma. For example:

The team includes analysts, developers, and testers.
The team includes analysts, developers and testers.
Leave a comment in the forum if you have any doubts, queries, or suggestions.
Leave a comment in the forum if you have any doubts, queries or suggestions.

To avoid confusion in more complex lists for which each item is composed of phrases that require commas, use semi-colons to separate items. For example:

Classic Components include the following: HorizontalLayout, VerticalLayout, Panel, Label, GridLayout, and FormLayout.
Several built-in HTML elements may be used: <div> and </div>, which are used for indicating web page sections; and <p> and </p>, which are used for paragraphs.

Case & Versions

There are a few different styling possibilities for the capitalization of certain words and words in certain situations. Although you may have your preferences, for better-looking documentation and easier reading and scanning of text, adhere to the rules on this topic presented in this section.

Capitalization

You should use title case for all titles, including page, section, and sub-section titles. This means using capital letters for the first letter of each word in a title or heading, but not usually for smaller words (e.g., "of", "in", "with").

= Style Guidelines for Vaadin Documentation

For a detailed description of capitalization rules, see Rules for Capitalization in Titles of Articles.

Product Names

Product names, such as Combo Box, should be capitalized in the same way as proper nouns. Some product names are the same as some class names. Be careful not to inadvertently use combined, camel-case when referring to the product. When referring to a class name, camel-case is used, but remember to use monospace formatting. Here are some examples:

Combo Box allows the user to choose a value from a filterable list of options presented in an overlay.
Combo box allows the user to choose a value from a filterable list of options presented in an overlay.
ComboBox allows the user to choose a value from a filterable list of options presented in an overlay.

The ComboBox class extends the ComboBoxBase class.

Vaadin Version Numbers

Avoid using explicit Vaadin version numbers in text (e.g., Vaadin 24). Instead, use something like [role="since:com.vaadin:vaadin@V24"] for parts of the documentation that apply since a specific version.

Using the integrated content areas in [since:com.vaadin:vaadin@V23.3]#Tab Sheet# is the easiest way to switch between the different content for each tab.

Using the integrated content areas in Tab Sheet (available in Vaadin 23.3 and later) is the easiest way to switch between the different content for each tab.

Try to write the documentation for features with the assumption that they’re available for general use in their final form, even if they’re still under development or only available in a pre-release. This is more agreeable to readers once a feature is available in a stable release. Otherwise, they’ll have to pause and consider if the documentation is relevant to them. Similarly, don’t assume the reader is familiar with how things worked in earlier versions of Vaadin; avoid such comparisons in any other section than release notes and upgrading guides.

Formatting

For certain texts, there are a few special ways in which they may be formatted. This includes the formatting of warnings and tips, how to mark up commands, Java classes, and the like. These are explained in this section.

Admonitions

Admonition blocks such as [NOTE], [TIP], and [WARNING] can be used to emphasize important information. However, don’t overuse them. They can interfere with the flow of the text. In general, there should be only a few of them in a document — no more than three, typically. Also, they should seldom be used at the start of a document, right after a page title or a section heading.

Where useful, include a title for an admonition. Preferably, use short, succinct titles. For brevity, you can sometimes exclude articles and use ampersand instead of "and". Be sure to format the title with title case.

Sparingly use brief sentences. Usually, a sentence in place of a title succinctly summarizes the main text of the admonition or could perhaps be an excerpt from it. Regardless of which, maintain a proper sentence structure — including ending with a period — and don’t use title case. Here are some examples:

Warning
Admonition Interruptions
Overusing admonition blocks tend to interrupt the flow of the text for the reader.
Warning
Don’t overuse admonitions.
Overusing admonition blocks tend to interrupt the flow of the text for the reader.

Emphasis

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

Style Element AsciiDoc Example Code Result

Class Names

[classname]`Component`

Component

Interface Names

[interfacename]`EventListener`

EventListener

Method Names

[methodname]`setValue()`

setValue()

Annotation Names

[annotationname]`@Route`

@Route

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+Shift+C]

Ctrl+Shift+C

Menu Choices

"Help > Updates" or menu:Help[Updates]

Help  Updates

Method Names

Use empty parentheses at the end of method names to denote that they’re methods. In general, don’t list parameter types for methods, unless this is required to refer to a specific version of a method. It may also be necessary to specify a parameter when it’s relevant in the context. For example:

Call setEnabled() to control if a component is enabled or disabled.
Call setEnabled to control if a component is enabled or disabled.
Call setEnabled(false) to disable it.

FAAF4D05-ED0A-4D13-A416-C8033BACC6A3