Global Audience and Inclusiveness
Introduction
Vaadin documentation is provided in English for the benefit of users all around the world. For many of these users, English isn’t their native language.
For this reason, we need to write in language that’s as clear and accessible as possible.
Principles of Writing for a Global Audience
- 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 easily digestible as follows:
Vaadin components support client-side validation to increase the responsiveness of the application. However, as a developer, you use this only for convenience, as it’s easy to circumvent client-side validation in the browser.
Here is another example, where 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 sets a component to disabled, it’s disabled on both the server and the client. An attacker can circumvent this on the client, because attackers have full control over anything in the browser. However, the server blocks any interaction with the disabled component. The server also prints a warning 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 the 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, take care to escape the data first. This would be necessary if, for example, you were using data from a database to set innerHTML, or using HTML mode in component captions.
- One verb in a sentence
-
For simplicity and ease of understanding, it’s a good general aim to try to have only one verb in each sentence.
However, where 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 have multiple verbs in a sentence.
For example:The request isn’t available in background threads, so the isAuthenticated() method shows 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. For this reason, the isAuthenticated() method shows the authentication state only in Vaadin request processing threads. In other cases, it returns false.
Inclusiveness
What Is Meant by Inclusiveness?
In simple terms, inclusiveness means not excluding anybody on an arbitrary basis, such as gender, age, disability, race, religion or sexual orientation.
Additionally, as far as possible, we want to include people of as wide a range of technical ability as possible. Although Vaadin’s technical documentation is aimed at an audience that has a certain level of technical awareness, we must be careful not to make too many assumptions about an individual reader’s knowledge and skill set.
The Audience Is … Everybody
We know that we have no preconceptions about our audience’s gender, race, ability, or any other aspect of their being. However, we need to remember to show this by not falling into some common language traps. Such traps often result from set expressions and language forms that have come to us from an earlier age.
English and Gender
The English language has one common issue (some might say "defect") that can make it difficult to demonstrate gender neutrality. The language doesn’t have a single, gender-neutral word to replace “he or she”, “him or her” or “his or her”.
The most obvious way to include both genders is to write “he or she” or “his or her” every time, as appropriate.
However, the problem with this is that it can quickly become awkward and repetitive.
For example:
If a user forgets his or her password, he or she should contact the support desk.
This is clearly awkward and intrusive.
The generally accepted workaround is to replace these phrases with “they”, “them” and “their”, respectively.
For example:
If a user forgets their password, they should contact the support desk.
Strictly speaking, this mixing of singular and plural isn’t grammatically correct. However, it’s a workaround that’s generally accepted as being a small price to pay to avoid the verbosity of the grammatically perfect version.
As an alternative solution in this particular case, you might also consider using a plural form to avoid the issue altogether.
For example:
Users who forget their password should contact the support desk.
Finding the Appropriate Level
As we can’t know exactly what each reader’s level of knowledge is, we have to use our judgment about what we can reasonably expect them to know, and what we need to explain.
Still, we hope that our customers find using our products to be an enjoyable and satisfying experience – and perhaps even an educational one.
If in Doubt, Explain
If you have some doubt about whether to explain some aspect more fully, it’s probably better to provide too much explanation than too little.
However, we still want our users to be able to get the core information from our documentation acceptably quickly, without having to read through too much text.
It’s a question of judgment, of course.
25985C00-CA5A-497D-B740-130570467A32