Documentation Style Guide

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.

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.

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.

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.

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:

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").

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:

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.

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.

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:

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

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:

FAAF4D05-ED0A-4D13-A416-C8033BACC6A3