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.
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 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.
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:
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.
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:
In these examples, the recommended spelling is American English, while those to be avoided are in British English.
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.
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:
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:
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.
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.
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.
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.
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.
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.
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.
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.
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.
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 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.
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.
Unlike other Latin abbreviations, this one may be used outside a parenthetical comment, in the main text of a sentence.
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.
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:
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:
</div>, which are used for indicating web page sections; and
</p>, which are used for paragraphs.
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.
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, 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:
ComboBoxclass extends the
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.
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.
Admonition blocks such as
[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:
Admonition InterruptionsOverusing admonition blocks tend to interrupt the flow of the text for the reader.
Don’t overuse admonitions.Overusing admonition blocks tend to interrupt the flow of the text for the reader.
Use the emphasis styles, such as
[classname]`ClassName` emphasis for class names and
[methodname]`methodName()` for methods.
|Style Element||AsciiDoc Example Code||Result|
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:
setEnabled()to control if a component is enabled or disabled.
setEnabledto control if a component is enabled or disabled.
setEnabled(false)to disable it.