- Ampersand ("&")
- Articles, Repeating in Lists
- Colloquial Expressions
- Cultural References
- Exclamation Mark ("!")
- Future Tense
- Introductory Clauses
- Latin Abbreviations
- Parallel Language Structures
- Product Names
- Proper Nouns
- Slash (“/”)
- Split Infinitive
- Vaadin Versions
Do not use the ampersand character in place of and in general text, unless space is limited.
Articles, Repeating in Lists
One common issue is whether to repeat articles in lists of two or more items.
In general, you can leave the second and subsequent articles out.
However, there are some cases where it might be better to include the articles:
Where there is possible ambiguity
A text field has a caption and input box
[This could mean that the text field has both a caption and an input box; or that the text field has a box that is for both the caption and for input.]
A text field has a caption and an input box
[Repeating the indefinite article removes the ambiguity.]
In a similar way, there can be ambiguity about the scope of an adjective.
a nested field and layout
[It is unclear whether the adjective nested applies to both field and layout, or only to field.]
a nested field and a layout
[Repeating the indefinite article removes the ambiguity.]
Where you want to emphasize individual items in a list
There are two ways: the right way and the wrong way.
The Good, the Bad, and the Ugly
The symbol @ is called the at character.
This comes from traditional accounting notation where the cost of multiple items at a specific cost would be given as, for example, 10 apples @ 5 cents = 50 cents, which would be read as 10 apples at 5 cents equals 50 cents.
The [ and ] characters are called brackets or square brackets.
For the ( and ) characters, see parentheses.
Avoid using colloquial expressions in Vaadin technical documentation, as they may be unfamiliar to people whose native language is not English.
Avoid congratulating the reader, for example, for successfully working through a tutorial and completing the process that the tutorial describes. It sounds patronizing.
Avoid using contractions (doesn’t, can’t, you’re, and so on) in technical documentation.
Be aware that users of our documentation come from many different cultures. Hence, avoid making references that depend on familiarity with any particular culture.
Exclamation Mark ("!")
Avoid using exclamation marks in technical documentation, unless it is as part of some code syntax. Its use in normal text is distracting and detracts from the professional tone. For example:
You have now created your component! [Avoid this usage.]
#!/bin/bash [The exclamation mark is part of the script syntax.]
Avoid using the future tense to describe the expected behavior of something. Instead, use the present tense. For example:
When the compilation is complete, the program displays summary information. Not will display.
Run the code in debug mode. Execution pauses at the breakpoint that you have specified. Not will pause.
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.
Additionally, we need to make the call to the REST service.
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.
Write out names of months in full, if space allows. If you need to abbreviate month names, use the following abbreviations:
Do not add a period to the abbreviated names.
In text in general, integers between 0 and 9 (inclusive) should be written in words, while other numbers should be written as numerals. Try to avoid beginning a sentence with numerals. For example:
The team consisted of one team leader, two senior programmers, and 10 junior programmers.
However, in certain contexts, it may be preferable to write all numbers in numerals. Such a context might be, for example, statistical or mathematical content, or where units are specified (such as degrees, metres, or kilograms). For example:
In a survey, 7 out of 10 developers said that they preferred Python to Perl.
You can calculate the value using
2 * π * r.
The sample was found to have expanded by 6 mm at the end of the experiment.
Similarly, use numerals for
numbers in a technical context, such as size of memory, processor speed, file sizes, etc.
ranges of numbers
For a decimal number greater than –1 and less than 1, put an explicit 0 before the decimal point. For example:
0.5 [Not .5]
-0.02 [Not -.02]
Avoid using Roman numerals (for example, I, IV, vii, ix).
Write out a number if it is an approximation, rather than an accurate figure. For example:
There must have been a thousand people at the meeting.
[Not There must have been 1,000 people….]
You had to write hundreds of lines of code.
[Not You had to write 100s of lines of code.]
Write out ordinal numbers (first, second, third, etc.) in full. Do not use 1st, 2nd, 3rd, etc.
Parallel Language Structures
When explaining or describing things that occur in some kind of list or sequence, try to use the same, or equivalent, language structures or terminology to talk about each item in the list. For example, consider the following structure that describes a list of things:
The first item is…
Next we have…
And now we come to the last object, which is…
The reader can more easily see the logical structure of the description in this improved version:
The first item is…
The second item is…
The last item is…
The ( and ) characters are known as parentheses.
Use them sparingly.
Consider whether you could achieve the same effect by simply using commas as delimiters.
As always, the guiding principle is simplicity, and clarity for the reader.
Using the passive too much can have the effect of making our language sound excessively formal.
Accordingly, avoid using the passive when it is possible to express the same idea elegantly and simply in active voice.
Use the required numeral and the percent sign ("%") with no space between them. If the percentage begins the sentence, write the percentage expression in words. For example:
In 99% of cases, the methodology works.
Ten percent of hacking attempts succeeded.
Do not use s in parentheses to indicate that there may be one or more of something. == For example
Inspect the error message[line-through](s) for more detailed information. [Avoid this form of optional plural.]
This usage can be confusing for the reader. Instead, choose an alternative wording, even if it is slightly longer. For example:
Inspect any error messages for more detailed information.
English has two main ways of forming a possessive: the apostrophe and the preposition of.
In general, use the apostrophe for people and animals. For example:
The team leader’s keyboardA manager’s salaryThe employees' well-beingThe horse’s mouth
Use the preposition of for things and ideas. For example:
the name of the methodthe beginning of the processthe keyboard of the computerthe door of the office
A third possibility is to use one noun as a descriptor of another. For example:
the method namethe computer keyboardthe office door
Notice that, in the last group of examples, the noun that is used as a descriptor is always singular, even if the word it governs is plural. For example:
the method namesthe computer keyboardsthe office doors
See also nouns as descriptors; apostrophe.
Product names, such as List Box, should be capitalized in the same way as proper nouns, and not as class names.
A class name can be used if specifically referring to a class; for example, [classname]
ListBox extends [classname]`ListBoxBase`.
A proper noun is a word or phrase that is the name of something or somebody; for example, Chrysler Building, Czech Republic, Indian Ocean, Pink Floyd, Windows 11.
It is distinct from a common noun, which is the "standard" type of noun that identifies the nature of something or somebody; for example, a building, a republic, an ocean, a band, an operating system.
Proper nouns are usually denoted by being capitalized. There are a small number of exceptions to this, usually by the choice of the person or organization that "owns" the name; for example, macOS. In these cases, we should try to use the "official" styling. If you are not sure of the correct form, an internet search is usually enough to find it.
Scanning is the process by which a reader quickly overviews the text to evaluate the content. The reader does this in order to find out whether it really does contain the information that they are looking for. If it does contain that information, they often also want to go directly to the most relevant part of the text.
We can make that process easier by making the core of each point as easy to find as possible. That means putting it near the beginning of the paragraph in which it appears.
We can also make sure that each new point appears in a new paragraph. This also helps the process of scanning.
Consider the following text:
In contrast to Vaadin Flow applications, where all application logic (including authentication and authorization) is processed on server side, Hilla applications involve the orchestration of server and client-side security. While the technical details are taken care of by the framework, it is important to understand how to design the application so that the server responds to client requests in a secure way.
This is good, but we could improve it by moving the most important points to a position near the beginning, and simplifying the language a little, as follows:
In Vaadin-Hilla-hybrid applications, we need to coordinate server and client-side security. This differs from Vaadin Flow applications, where all application logic (including authentication and authorizations) runs on the server side. We need to design the application so that the server responds to client requests in a secure way, even though the framework takes care of the technical details.
We need to avoid slang for two good reasons. One reason is that it detracts from the professional style that we are trying to convey with our documentation. The other reason is that non-native speakers may not be familiar with slang terms. That would impact the accessibility of our documentation.
The slash character is often used to indicate one or more possibilities from a group. The slash character should be preceded and followed by a non-breaking space. For example:
The library contains routines to facilitate input / output.
Try to avoid excessive use of the slash character, particularly when the words and or or would suffice. For example:
I was responsible for bug-fixing and maintenance work. [Not bug-fixing / maintenance work.]
Please get back to me if you have any questions or queries. [Not if you have any questions / queries.]
Avoid using slashes in abbreviations. For example:
in charge [Not i/c.]
AC-DC [Not AC/DC, unless in the context of Australian rock groups.]
Do not use the slash character to write fractions, such as 1/2 or 3/4, as these may be liable to misinterpretation.
Instead, use the ½ (
½ in AsciiDoc), ¼ (
¼), or ¾ (
¾) characters, if appropriate.
If the required character is not available, use a decimal or spell it out.
The inverse of 8 is one-eighth.
The inverse of 8 is 0.125.
Although split infinitives are generally considered to be acceptable these days, it is worth considering whether you could easily write your sentence so as to avoid it.
However, there may be some cases where strictly imposing the ideal of avoiding split infinitives could result in an awkward sentence or even introduce ambiguity. Clearly, we need to prioritize simplicity, clarity, and accuracy at all times, even if it means we have to compromise on elegance.
The character "_" is called the underscore character.
You can avoid formatting problems in AsciiDoc by using the
_ entity reference.
A space should be inserted between the numeric quantity and the units. Abbreviated forms of units are written in the singular. For example:
The maximum permissible weight is 28 lb. [Not 28 lbs.]
The following are the standard abbreviations for common units:
° (no space)
It is very common to use a compound expression with a numeric value and units as a descriptive phrase. In such cases, use a hyphen to join the compound expression. Notice that the singular form of the unit is always used. For example:
A 22-page book. [Not A 22-pages book.]
A twenty-mile journey. [Not A twenty-miles journey.]
A 25,000-ton ship. [Not A 25,000-tons ship.]
Do not use Vaadin 14 or other Vaadin version numbers in text. Instead, use the [role="since:com.vaadin:vaadin@V19"] tag to indicate version numbers.
Do not use the character x as a multiplication sign.
Instead, use the multiplication symbol × (
× in AsciiDoc).