Word List

Word List and Quick Reference

Miscellaneous Terms

"3D"

Abbreviation of three dimensions or three-dimensional.
Not 3-D.
For example:

The image is visible in 3D. The system displays a 3D image.

A

"a", "an"

The choice of whether to use a or an depends on the sound of the following element, not purely on whether that element begins with a vowel.

If the sound of the next item is a vowel sound, use an; otherwise, use a.
For example:

She decided to do a university course.
[University begins with a consonant sound.]

It was an unusual choice.
[Unusual begins with a vowel sound.]

We stayed in a hotel on the Left Bank.
[Hotel begins with a consonant sound.]

It was an honest mistake.
[Honest begins with a vowel sound.]

The same principle applies to acronyms.

Decide on how the acronym is usually read – as a word or as individual letters – and select a or an based on the resulting initial sound.

For example:

The product comes from a US company.

Send me an SMS when you are ready.
[SMS is read as ess_em_ess, so it begins with a vowel sound.]

He is a former member of a SWAT team.
[SWAT is generally pronounced as one word – swat.]

"above"

Do not use above to indicate the position of an item on a page. Various devices, screen readers and browsers may position elements in different places. Instead, use previous or earlier.

"add-in"

"add-on"

“advice”

"Advice" is an uncountable noun. For that reason, it can’t be used with the indefinite article (an advice) and it can’t be plural (advices).
If you want to use the indefinite article, you need to introduce another word, such as piece or bit. For example:

The developer gave me a good piece of advice.

You can use quantifier phrases such as some and a lot of.
For example:

The user guide contains a lot of good advice.

"agnostic"

This term is sometimes used to indicate the absence of a dependence on some other software component, such as an operating system or platform.
It is better to use a clearer term, such as platform-independent.

"aka"

This is an abbreviation of also known as. It has its origins in police usage and, hence, conveys an inappropriate tone for software documentation.

Instead, use parentheses or the word or.
For example:

The company specializes in software as a service (SaaS).
Each instantiated object of the class has a separate copy, or instance.

"a.m.", "p.m."

Write these in lower case, with periods. Insert a non-breaking space (  in AsciiDoc) between the time in numerals and a.m. or p.m.
For example:

The meeting started at 9∶15 about a.m.
We received the email at 5∶00 p.m. yesterday.

"alright"

Avoid using alright.
Instead, use all right.

"alternate", "alternative"

Alternate is a verb that describes something that switches repeatedly between two states, or conveys the concept of every other.

Alternative is a noun or an adjective that indicates two possible options.
For example:

The weather alternated between sunny and cloudy.

An alternative to installing the software using a package manager is to download it as an AppImage.

"America"

Do not use America or American as synonyms for United States or US. In general, use US, as both a noun and an adjective.

If you live in the US, contact our San Francisco support desk.

You need to comply with US data protection legislation.

ampersand ("&")

Do not use the ampersand character in place of and in general text, unless space is limited.

"and / or"

Insert a non-breaking space (  in AsciiDoc) before and after the slash ("/") character in and / or.

"anti-malware"

"antialiasing"

"antivirus"

"app"

Use application, rather than app.

"approximately"

Write this in full; do not use approx.

"arabic"

Use lowercase arabic to refer to the system of numerals.

"as if" or "like"?

Consider this sentence:

It looks as if it’s going to rain.

Here, the clause it’s going to rain contains a finite (complete) verb (is going to rain).

In this situation, we should use as if to connect the two parts of the sentence. It is not correct to say, It looks like it’s going to rain, although this is a very common grammatical error.

Here is another sentence:

It looks like rain.

Here, the noun phrase rain does not contain a finite verb. In this situation, we should use like to connect the two parts of the sentence.

Another way of thinking of this is to say that as if "expects" to be followed by a verb clause. In contrast, the word like "expects" to be followed by a noun or a noun phrase.

Some other examples:

Treat the issue as if it were a bug.
[Verb clause]

They treated me like a VIP.
[Noun phrase]

“as” or “like”?

As "expects" to be followed by a verb clause.
On the other hand, like "expects" to be followed by a noun phrase (that is a phrase that has the grammatical function of a noun).
For example:

Edit the file as you would normally.
[Not like you would.]

Make the amendments as described below.
[Not like described.]

As I have already mentioned, the software is open-source.
[Not like I have already mentioned.]

"as such"

As such does not mean for that reason.

Instead, it means in its role as the previously mentioned thing.
For example:

This software is the most capable of its peer group and, as such, is an excellent buy.
[That is, as the most capable of its peer group….]

I was the chief designer on this project and, as such, I take full responsibility for design defects.
[That is, as the chief designer….]

As such is often incorrectly used in place of phrases like so or consequently. Here are some examples of incorrect usage:

Developers appreciate the convenience of the toolkit and, as such, it is a popular choice.
[Incorrect]

The team were in a hurry to complete the project and, as such, made several poor decisions.
[Incorrect]

"ASCII"

"aspect ratio"

"assembly language"

Use assembly language, not assembler.

“asynchronous”

The adjective is asynchronous. The adverb is asynchronously.
Do not use async.

"authenticate"

"auto-"

No general rule exists on whether to hyphenate a word that begins with the prefix auto-.
It is best to check in the dictionary.

If the word is not given either in this guide or in the Merriam-Webster online dictionary, do not invent it yourself; use another term, for example with the adverb automatically.

"autosave"

“awesome”

In its literal meaning, awesome is used to describe something that causes awe, a feeling of respect blended with fear or wonder.

The launch of the huge rocket on a pillar of smoke and flames was an awesome sight.
The enormously powerful waterfall is really an awesome spectacle.

In modern informal speech, awesome has been diverted from its literal meaning to be a synonym for very good.
Please avoid this usage in technical documentation.

B

"back button"

"backup", "back up"

The noun and adjective are backup. The verb is to back up. For example:

Confirm that the backup completed successfully.
[Noun]

It is vital to have reliable backup procedures in place.
[Adjective]

You should back up all your files regularly.
[Verb]

The data is subsequently backed up to the cloud.
[Verb]

“back end”

"backward compatibility"

The noun is backward compatibility. The adjective is backward-compatible.

"backspace"

"bandwidth"

"base64"

"below"

Do not use below to indicate the position of an item on the screen, as different devices and browsers may position elements differently.

Consider using later or in the following.

"beta"

The word beta should be written in lowercase, unless it appears differently as part of a defined product name.

"big data"

The noun phrase is big data. The adjective phrase is big-data.

"big-endian"

"blacklist"

Do not use the term blacklist. Instead, use deny list.
The opposite is allow list, not whitelist.

"blind"

Avoid using blind in an idiomatic or metaphorical sense.

To refer to people, use, for example, a blind person or a visually impaired person (whichever is more accurate in the context).

See also color blind.

"Bluetooth"

Bluetooth is a proper noun, so it should be capitalized.

"Boolean"

Capitalize Boolean in general use.

"bot"

“both”

"Both" is an emphatic word that applies specifically to two stated things.
It cannot be used for more than two.
For example:

This functionality is available in both Eclipse and NetBeans.

It is incorrect to say, for example:

This functionality is available in both Eclipse, NetBeans, and IntelliJ IDEA.

To apply similar emphasis to more than two things, it would be necessary to say something like:

This functionality is available in all of Eclipse, NetBeans, and IntelliJ IDEA.

However, it might be more elegant to say, for example:
Eclipse, NetBeans, and IntelliJ IDEA all have this functionality.

"breakpoint"

"browsable"

"built-in"

The adjective is built-in when it is used attributively (that is, before the noun that it describes).
When it is used predicatively (that is, after a verb such as be, seem, look), the adjective phrase is built in. For example:

The device has a built-in DVD drive.
[The adjective is used attributively.]

The DVD drive is built in.
[The adjective is used predicatively.]

The device has a DVD drive built in.
[The adjective is used predicatively.]

C

"cache", "cached", "caching"

"callback", "call back"

The noun and adjective are callback. The verb is call back.

"call-out", "call out"

The noun and adjective are call-out. The verb is call out.

"cancel"

canceled, canceling, cancellation.

"catalog"

Use catalog, not catalogue.

"cell phone"

Do not use cell phone.
Instead, use mobile or mobile phone.

"cent"

The cent symbol (¢) can be written as ¢ in AsciiDoc.

"chat"

Chat may refer to different activities, depending on the context.
Use chat to refer to exchanging text messages in real time, if the context makes the meaning clear.
Use voice chat to refer to communicating by voice.

"check"

Do not use check to refer to selecting a checkbox in the user interface.
Instead, use select.

"check mark"

In the UI, a check mark is a visual indication that an item is selected.

"checkbox"

The spelling is checkbox.

Use select and clear to refer to user interaction with checkboxes.

"click"

Click is both a verb and a noun.
More-specific variants are left-click, right-click, and double-click (all hyphenated).
For example:

Enter the required details and click OK.

Right-clicking on the dropdown presents the user with more options.

“client side”

When used as a noun phrase, client side has no hyphen:

The validation is handled on the client side.

When used as an adjective phrase, it should be written with a hyphen to avoid ambiguity:

Client-side processing handles the validation.

"client / server"

Use non-breaking spaces before and after the slash ("/") character. In AsciiDoc, this would be written as client / server.

"cloud"

"codebase"

The spelling is codebase; not code base.

colon (“:”)

The function of a colon in a sentence is to signal the beginning of an explanation or a list.
Often, we can think of it as saying
and this is it…
or
and the following is what I’m talking about….
Some examples of this are:

There can be only one reason he is late: he has missed the flight.
Annabel has three valuable characteristics: she is clever, she is conscientious, and she is honest.
On seeing the results of my work, I felt only one emotion: pride.

A colon is also commonly used to introduce a list, particularly at the end of a sentence.
For example:

The parameter can be of several types: integer, boolean, or string.
Three cities are in the running to stage the next Olympics: Beijing, Chicago, and Melbourne.

A colon should not be used to join two full clauses outside the uses mentioned here.
If you are looking for the right punctuation to join two clauses that have some logical relationship, consider using a semi-colon.
Do not use a comma for this purpose. (See comma splice.)

Vaadin uses US English in its documentation. US usage allows a colon to be followed by a sentence beginning with a capital letter, if that sentence is the first of two or more sentences that are governed by the same colon.

There may be several reasons to learn Esperanto: It is completely regular, so you do not need to learn a lot of exceptions. It is not associated with any specific country, so has no political baggage. Finally, it is just fun to learn.

However, if the colon governs only one sentence, begin the sentence with a lowercase letter:

I can give you one good reason to learn Esperanto: it is fun to learn.

"color-blind"

Use the term color-blind only in its literal sense, to refer to a person who is unable to distinguish certain colors.

"combo box"

Not combobox.

"command line"

When it is used as a noun phrase, write command line. When it is used as an adjective phrase, write command-line. For example:

You can invoke the tool from the command line.
[Noun phrase]

There are several command-line options.
[Adjective phrase]

"command line interface"

This is a common, easily recognized phrase, so it is unnecessary to hyphenate command line here.

In the first reference in the document, write this as command line interface ("CLI"). In subsequent occurrences, it is acceptable to write it as CLI.

"command prompt"

In the context of the command line interface, the command prompt indicates the location where the user may enter a command. Typical command prompts are "$ " (in Unix-like systems) and "C:\> " (in Windows-based systems).

"consist of"

This indicates that one thing is made up of one or more other things, and nothing else. If you want to say that one thing is made up of one or more things plus some other things, use include. For example:

The course consists of six modules.
[In other words, there are six (and only six) modules in the course.]

The course includes two modules on object-oriented design.
[In this case, the two modules on object-oriented design are just a part of the course.]

"config"

Avoid this as an abbreviation for configuration. Spell it out in full.

"CPU"

"CSS"

It is acceptable to use CSS, rather than write out cascading style sheets in full.
Do not use the extension .css to refer to a file type.

"cross-site request forgery"

On the first mention, write this as cross-site request forgery (CSRF). On subsequent mentions, CSRF is sufficient.

"CSV"

Do not use the extension .csv to refer to a file type.
Instead, use the capitalized abbreviation CSV.
For example:

You can download this as a CSV file.
[Not a .csv file.]

D

“data”

Although data is, strictly speaking, a plural Latin form, the generally accepted convention is to treat it as singular. For example:

We need to ensure that the data is encrypted.
[Not the data are encrypted]

"daylight saving time"

"decrement"

The verb decrement means to decrease an integer by a specified value. It is the opposite of increment.

definite article (“the”)

"deprecate"

In the context of software development, if something is deprecated, it means that it is recommended not to use this thing.
It does not mean that it is not possible to use it.

The term deprecated is often used in situations where that particular thing is scheduled to become unavailable at some point in the future.

"desire"

Do not use desire as a synonym for want.
Instead, use want.

"determinate progress bar"

A determinate progress bar is a progress indicator that informs the user how much of a process has been completed, and how much remains to be done.

"DevOps"

An abbreviation of development operations. Write it as DevOps.

"dialog"

A dialog or dialog box is an element of the user interface.
A dialogue is a conversation between two people.

"different"

Use different from, rather than different than or different to.

"direction keys"

Do not use the term direction keys.
Instead, use arrow keys.

"directory"

Use directory, instead of folder, unless there is a good reason to do otherwise.
One such reason might be that the tool under discussion uses the term folder in its user interface.

"distributed denial-of-service"

On the first mention, write distributed denial-of-service (DDOS). On subsequent mentions, it is sufficient to write DDOS.

"DNS"

DNS is an abbreviation of Domain Name System (not Server), which is a protocol.
A server that operates this system is a DNS server.
A client of such a server is a DNS client.

"document"

Write this in full.
Do not write doc.

"domain name registrar"

"dos and don’ts"

Use overlay rather than dropdown.

"due to"

Avoid using due to.
Instead, use because of or as a result of.

E

"e-book"

"e-commerce"

"e.g."

Avoid using e.g.
Instead, write for example.

“either”

Like the word both, the word either is used in the context of two things.
For example:

The parameter can be either an integer or a boolean.

It is not correct to use either where there is a choice between more than two things.
For example, this is incorrect:

The parameter can be either an integer, a boolean or a string.

In such a case, we could say, for example:

The parameter can be an integer, a boolean, or a string.

For added emphasis, we could also say:

The parameter can be any of an integer, a boolean, or a string.

For clarity, either should be placed as close as possible to the point where choice occurs.
For example:

You can choose either to ignore the message or to fix the problem before continuing.
[This is OK, because the choice is either to ignore or to fix.]

You can either choose to ignore the message or to fix the problem before continuing.
[Inappropriate, because the choice is not whether to choose or not to choose.]

"element"

Use element, rather than tag, when referring to HTML elements.

"email"

"end user"

The noun is end user. The adjective phrase is end-user. For example:

The choice of licence depends on the number of end users.
This will minimize the level of end-user support that you need to provide.

"enter"

In the context of IT systems, to enter refers to inputting a specific piece of data to the system. For example:

Enter your user ID and press OK.

"Esc key"

"etc."

This abbreviation is always terminated by a period.

Do not use etc. in situations where it is not clear exactly what it means.
For example:

Always be sure to include the currency symbol, such as "$", "£", "€", etc.
[Here, it is clear that etc. refers to all the other possible currency symbols.]

Check that the problem was not caused by a misspelt variable name, etc.
[In this case, it is unclear what other issues might have caused the problem.]

F

"F1", "F2", "F3", etc.

"FAQ"

FAQ is an abbreviation for frequently asked question. The term is sufficiently well known for it not to need explanation.
The plural is FAQs.

"fast-forward"

Fast-forward can be a noun, an adjective or a verb.

"fewer"

Fewer (not less) should be used with countable nouns. For example:

There were fewer problems with this version of the software.
[Not less problems.]

Fewer and fewer people use landlines these days.
[Not less and less people.]

"fiber optics"

"field"

Use the term field in the context of databases.
Do not use field in the context of the UI.
Instead, use, for example, box.

"filename"

"firewall"

"firmware"

"floating-point"

Floating-point is an adjective.

"following"

Following may be used with some more specific term. For example:

the following example
the following text
the following procedure

However, it may not always be necessary to be so specific.
We may use the expression the following as a noun phrase on its own.
For example:

The following is an example of how to use this functionality.
It may be instantiated using the default parameters, as in the following:

"font size"

"for example"

Use for example in preference to e.g.

If you use for example in the middle of a sentence, use a semi-colon if there is a possibility of doubt as to which part of the sentence it relates to.
For example:

There are some differences between US and UK spelling, for example, the preference for z or s in verbs that end in -ize.
[On first reading, the reader may hesitate over which part of the sentence for example refers to.]

There are some differences between US and UK spelling; for example, the preference for z or s in verbs that end in -ize.
[The semi-colon makes it easier for the reader to interpret the sentence correctly on first reading.]

“former”

The word former identifies the first of two options previously mentioned. (Former is often used in conjunction with latter, which indicates the last of two options previously mentioned.)
It is not correct to use former in a situation where more than two options have been mentioned.
For example:

Anil spends his spare time playing squash and doing crosswords. The former helps him to stay fit; the latter keeps his brain sharp.

Former is also used as an adjective to indicate that a person or place had a certain role in the past. For example:

Anne is a former systems analyst who now acts as a security consultant to the company.
[That is, Anne used to be a systems analyst.]

The company has its offices in a former bakery.
[That is, the company’s offices used to be a bakery.]

"forward compatibility"

The noun is forward compatibility.
The adjective is forward-compatible.

"freeze"

Do not use freeze to refer to a situation when a program stops responding.
Instead, write stops responding.

“front end”

The noun phrase is front end.
The adjective is front-end.
For example:

Processing takes place at the front end.
Front-end processing is kept to a minimum.

G

"Gbps"

Abbreviation of gigabits per second.
Do not use Gb/s.

"GDPR"

On the first mention, use the General Data Protection Regulation (GDPR).
On subsequent mentions, use the GDPR.

"GIF"

Do not use the extension .gif to refer to a file type.

"gray"

H

"half"

In compound phrases with half, use a hyphen. For example:

half-life
half-length
half-price

"handheld"

"hang"

Do not use hang to refer to a situation when a program stops responding.
Instead, write stops responding.

"hard disk"

"hard drive"

"hard-code"

The verb is hard_code.
The adjective is hard-coded.

“he” / “she” / “they”

It is important to avoid using gender-specific pronouns (unless there is a significant reason for doing so).
Do not overuse he / she or he or she, as this quickly becomes tedious.

The generally accepted approach is to use the pronoun they.
For example:

Each person must do what they think best.
[Not what he or she thinks best.]

However, if you can easily avoid the issue by using the plural, do so.
For example:

People must do what they think best.

"hexadecimal"

Write out hexadecimal in full.
Do not abbreviate it to hex.

“hierarchy”

“his” / “her” / “their”

"hit"

Do not use hit to refer to pressing a key.
Instead, use press.

"home page"

“hopefully”

Do not use hopefully to mean it is hoped that.
For example:

Hopefully, the new version will be released at the beginning of July.

Instead, use <the subject of the sentence> hopes to.
If you must use a passive construction, write it is hoped that.
For example:

The company hopes to release the new version at the beginning of July.
or
It is hoped that the new version will be released at the beginning of July.

"host name"

Use hyperlink in preference to link.

I

"i.e."

Avoid using i.e.
Instead, use that is.

"I/O"

It’s OK to write I/O, with no spaces.
If you expand it to input / output, insert non-breaking spaces (&nbsp;) around the slash character.

“if” clauses in the future

Clauses that refer to conditions in the future use the present tense.
The "result" clause uses the appropriate future form or imperative form.
For example:

If there are any further releases, you will receive an advisory email.
[Not If there will be….]

Send us a message via our contact page if you have any problems.
[Not If you will have….]

"if" or "whether"

Use if in clauses that express a simple conditional meaning.
Use whether in clauses that express uncertainty between two possibilities. Sometimes, either is acceptable.
For example:

Let me know if you need help.
[This is a simple condition; that is, if the situation arises that you need help, let me know.]

Let me know whether the fix works.
[That is, let me know which of the situations is true: does the fix work, or doesn’t it work?]

“in order to”

Use in order to for clarity, especially after verbs that are followed by the infinitive (to) form, such as need, want, start.
For example:

This the information you need to use the components correctly.
[The reader may misinterpret this on first reading.]

This the information you need in order to use the components correctly.
[Slightly more verbose, but clearer.]

"indent"

Indent is a verb that means to apply a greater left (and sometimes right) margin to text than that of the preceding material.
The purpose of indentation is to show some distinction between one piece of text and the next.

Do not use outdent, as it is often unclear what exactly this means in a given situation. Look for a different way to express this idea.

"indeterminate progress bar"

An indeterminate progress bar is a progress indicator in a situation where it is not possible to determine and show how much of the process remains to run.

“information”

"Information" is an uncountable noun. In other words, we cannot talk about one information, two informations, etc.
For the same reason, we cannot say an information, as this implies a quantity of one.

If we want to talk about quantity in relation to information, there are several options:

  • use an intermediary word, such as piece or bit

  • use a quantifier, such as a lot of, lots of, some, a little, etc.

"input"

Do not use input as a verb.
Instead, write enter.

"internet"

"Internet of Things"

On the first mention, write as Internet of Things (IoT).
On subsequent mentions, write as IoT.

"insertion point"

The point on the screen where the user enters data.

"italics"

The noun is italics.
The adjective is italic.
The verb is italicize.

“its” or “it’s”

The possessive form of it is its, with no apostrophe.
This is logical and consistent with the other possessive adjectives:
Imy
youyour
hehis
sheher
theytheir
etc.
Possessive adjectives have no apostrophes.

It’s (with the apostrophe) is a contracted form, similar to I’m, you’re, he’s, etc.
Here, the apostrophe performs its classical role of indicating that letters have been omitted.
It’s can mean it is or it has; the context will always tell us which meaning is intended.

It’s easy to make a mistake.
[It’s must mean it is, since It has easy… makes no sense at all.]

It’s been a difficult day.
[It’s must mean it has, since It is been… makes equally little sense.]

See also contractions.

J

"JavaScript"

"JPEG"

Do not use the filename extension .jpg to refer to a file type.

"justified"

Text that is justified is aligned on the left and on the right.

K

"Kbps"

Abbreviation for kilobits per second.
Don’t use kb/s.

"key"

Don’t use this as a synonym for "crucial".

"key-value pair"

Use a hyphen, rather than an en-dash.

"keypress"

"keystroke"

"keyword"

"knowledge base"

L

“-l-” or “-ll-”?

In US English (which is used in Vaadin documentation), if a verb ends in the letter l, the final l is not usually doubled when a suffix (-ing, -ed, -er) is added.
The exception is when the final syllable is stressed.
For example:

cancel, canceling, canceled
travel, traveling, traveled
excel, excelling, excelled

"labeled"

“latter”

"layout", "lay out"

The noun is layout.
The verb is lay out.

"lead"

The past simple and past participle of lead is led. For example:

This situation led to a number of problems.
He has led the company since 2006.

"leverage"

Avoid using this as a verb.
Consider using take advantage of or make effective use of.

“like” or “as”?

"list box"

"livestream"

"login"

The noun is login.
The verb is to log in (to).

"lower"

Do not use lower to refer to earlier versions of software.
Instead, use earlier.

M

"macOS"

Use macOS, even at the beginning of a sentence.

"mailbox"

"markup"

The noun is markup.
The verb is to mark up.

"master / slave"

Avoid this term.
Instead, consider using primary / subordinate.

"matrix"

The plural is matrices.

"Mbps"

Abbreviation of megabits per second.
Not Mb/s.

"metadata"

"method"

As our documentation deals extensively with Java objects and methods, avoid using method to mean way or process.

"MIME"

It is usually unnecessary to write out this term in full.
However, if it is required for some reason, it is multipurpose internet mail extensions.

"mobile"

Use mobile, mobile phone, or mobile device.
Do not use cell phone.

"movable"

Do not use moveable.

"much"

Much is frequently used in questions and negative statements, but not usually in positive statements.
In positive statements, use an alternative expression, such as a lot of, a great deal of, or a large amount of.
For example:

Is there much difference between version 1 and version 2?
No, there is not much difference between version 1 and version 2.
Yes, there is much difference between version 1 and version 2.
Yes, there is a lot of difference between version 1 and version 2.

"multifactor authentication"

N

"N/A"

Use this abbreviation of not applicable in tables or other contexts where space is limited.

"name server"

"namespace"

"NAT"

Abbreviation of network address translation.

"needed"

Don’t use needed attributively (that is, before the noun phrase that it describes). Instead, use required. For example:

Edit the code and make the required changes.

Edit the code and make the needed changes.
[Do not use needed attributively.]

Edit the code and make the changes that are needed.
[It is OK to use needed predicatively.]

"network"

Write network out in full.
Do not shorten it to net.

"NoSQL"

“npm”

"null"

In general contexts, use the term null to refer to a null value.

O

"OAuth 2.0"

"of"

Do not add of to prepositions where it is not necessary. For example:

inside of the parentheses
[Instead, write inside the parentheses.]

off of the premises
[Instead, write off the premises.]

"OK"

Write OK, not okay.

"on-premises"

Write on-premises in full, not on-prem.

"once"

Do not use once to mean after, as it can be confusing.
Use after or when.
For example:

Once you have created the object, you need to initialize it.

Instead, write
When you have created…
or
After you have created…

"open source"

As this is a common phrase, it is unnecessary to use a hyphen, even when it is used as an adjective phrase.

"OS"

Is it unnecessary to write out this abbreviation of operating system in full.

"over"

Do not use over in the sense of more than. Instead, use more than.

“overlay”

P

"parent-child"

"PDF"

Do not use the extension .pdf to refer to a file type.

"per"

Use per instead of the slash character ("/") to refer to a rate. For example:

bits per second
[Not bits/second.]

words per minute
[Not words/minute.]

"persist"

The verb persist does not take an object (that is, it is intransitive).
For example:

We want the user ID to persist between sessions.
[That is, the user ID should be retained.]

We want to persist the user ID between sessions.
[The verb persist does not take an object.]

"please"

Do not use please in the context of instructions.
It is unnecessary.

"plugin"

"PNG"

Do not use the file extension .png to refer to a file type.

"post"

Do not use post as a synonym for after.
Instead, use after.

"postal code"

Use postal code rather than postcode or zip code.

“practice”

In US English, practice is a noun and a verb.

"precondition"

"press"

Use the verb press to refer to pressing a key or key combination.
Do not use hit in this context.

Q

R

"real time"

The noun phrase is real time.
The adjective phrase is real-time.
For example:

The data is retrieved in real time.
Real-time processing takes place at the frontend.

"regular expression"

Do not use regex.

“repository”

Do not use repo.

“respectively”

The adverb respectively is used in a well-defined grammatical context.
It has the function of distributing meaning over a defined set of entities.
For example:

The research department, marketing department, and customer services department are located in San Francisco, New York, and New Orleans respectively.

Do not use respectively in any other construction.

"REST"

It is unnecessary to write out this abbreviation of representational state transfer in full.

"runtime"

S

"(s)", "(es)"

Do not append (s) or (es) to a singular word in order to indicate that the item in question may or may not be plural.
For example:

Select the file(s) that you wish to upload.

Instead, either use the plural word only, or explicitly give both forms.
For example:

Select the files that you wish to upload.
or
Select the file or files that you wish to upload.
[It is usually unnecessary to be so explicit.]

“-ise” or “-ize”

In US English, the suffix -ize is generally preferred over -ise.

“separator”

Use divider rather than separator.

“server side”

"service level agreement"

On the first mention, write it as service level agreement (SLA).
On subsequent mentions, write it as SLA.

"setup"

The noun and adjective are setup.
The verb is to set up.

"SHA-1"

"ship"

Do not use ship to refer to software releases.
Instead, use release.

"sign-in"

The noun and adjective are sign-in.
The verb is to sign in (to) (not to sign into).

"smartphone"

Do not use the term smartphone.
Instead, use mobile or mobile phone.

“software as a service”

At the first mention, write software as a service (SaaS).
On subsequent mentions, write SaaS.

"space key"

"specification"

Write specification out in full.
Do not abbreviate it to spec.

"ssh", "SSH"

ssh is the terminal utility.
SSH is the associated communications protocol.

"startup"

The noun and adjective are startup.
The verb is to start up.

"status bar"

"style sheet"

"subclass"

Subclass is a noun and a verb.

"subnet"

"sync"

The verb forms are sync, syncing, synced.

T

"tar"

Do not use the extension .tar to refer to a file type.
For example:

a tar file

“that”

If the word that is optional, include it for clarity.
The goal, as always, is to help the reader to interpret each phrase and sentence correctly at the first reading.
For example:

… to guarantee your software works correctly,

… to guarantee that your software works correctly.

“that” or “which”?

In defining relative clauses (see relative clauses), we can use either that or which.
For example:

The company that developed the software provides excellent support.
or
The company which developed the software provides excellent support.

However, in non-defining relative clauses (see relative clauses), we cannot use that.
For example:

I emailed technical support at BrilSoft, which developed the software.
[Not … at BrilSoft, that developed the software.]

“their” or “they’re”?

Because the pronunciation of their and they’re is identical, it is easy to write the wrong form.
This error is less likely to happen in our technical documentation, as we have made the decision not to use contracted forms.
In general, the form they’re should not be used in our technical documentation.

“time frame”

Use time frame rather than timeframe.

"time out"

The verb is time out.
The noun and adjective are time-out.

"time stamp"

The noun is time stamp.
The adjective and verb are time-stamp.

"time zone"

If a time zone has an unambiguous name, write it out in full, capitalized on the first use.
Use Coordinated Universal Time (UTC) rather than Greenwich Mean Time (GMT).
For example:

The first backup was set to run at 09∶00 Coordinated Universal Time (UTC).
The second backup was set to run at 23∶00 UTC.

If the time zone does not have a name, or to guard against misunderstanding, use the form UTC-n or UTC+n.
For example:

The videoconference is scheduled for 14∶30 UTC-7.
The system went down at 21∶43 UTC+9.

"toolkit"

"touchscreen"

"trailing"

Use trailing to refer to characters that occur at the end of a string.
The opposite of trailing is leading.

"trojan"

Use trojan or trojan horse.

U

"United Kingdom"

Use the United Kingdom or the UK to refer to the sovereign state.
Do not use Great Britain, Britain, or England in this sense.

“unique”

Something is either unique or it is not. There can be no degrees of uniqueness.
Hence, avoid using such expressions as very unique or rather unique.

"unzip"

Do not use unzip.
Instead, use extract.

"uppercase"

"URL"

The plural is URLs.

"US"

Do not use U.S.

"username"

"UTF"

UTF-8, UTF-16, UTF-32.

"utilize"

Avoid utilize.
Instead, use use.

V

"v."

Use v. as the abbreviation for version.
For example:

Atom v. 1.57.0

However, the exception is Vaadin’s own software, since historically a capital V is used in this context.
For example:

Vaadin 21
This was introduced in V 20.

"via"

Avoid using via.

"vice versa"

Avoid using vice versa, as it is often unclear exactly what is meant.
Use more-specific language.

"videoconference"

"voicemail"

"vs"

Write versus in full, or abbreviate it to vs without a final period.
Avoid using versus in the sense of compared with or as opposed to.

W

"W3C"

"was" or "were"?

In English, the subjunctive mood has largely fallen out of use.
However, it still exists in certain set constructions.
For example:

If I were you…
[Not If I was you….]

In other constructions, using a subjunctive form is generally optional.
For example:

If he were here, he could explain it to you.
If he was here, he could explain it to you.
[Both of these are acceptable.]

It is necessary that you be here.
It is necessary that you are here.
[Both of these are acceptable.]

It is important that she have experience.
It is important that she has experience.
[Both of these are acceptable.]

In some cases, you can avoid the issue by using alternative forms.
For example:

It is necessary for you to be here.
It is important that she should have experience.

"web"

Use web when referring to the World Wide Web.

"web-based"

"webpage"

"website"

"well-being"

“which” or “that”?

"while"

Use while in expressions of time.
Do not use while as a synonym for although or whereas.
For example:

While it is possible to write code using an ordinary text editor, using an IDE has signficant advantages.
Although it is possible to write code using an ordinary text editor, using an IDE has signficant advantages.

The previous version was written in C++, while the current version is Java-based.
The previous version was written in C++, whereas the current version is Java-based.

"white paper"

"who" or "that"?

Use who, rather than that, in relative clauses that refer to people. For example:

Users who require training. [Not Users that require training.]

"whom"

In general, try to avoid using whom. It can sound pretentious.

However, it is sometimes difficult to avoid elegantly.
For example:

To whom were you talking?
[This is grammatically correct, but it sounds pretentious.]

Who were you talking to?
[This sounds much more natural.]

Sometimes it is preferable to use whom in order to avoid an awkward sentence.
For example:

This is the customer for whom we selected the appropriate product, rewrote the core module, and delivered training to the sales and marketing staff.

This is the customer who we selected the appropriate product, rewrote the core module, and delivered training to the sales and marketing staff for.
[Here, the preposition _for
is so far from its associated relative pronoun (who) that the reader is likely to lose track of the meaning.]

“whose” or “who’s”?

Although these two words sound exactly the same, they have completely different meanings.

Whose means of whom or of which.
For example:

This is the user whose account was blocked.
[That is, the user of whom the account was blocked.]

This is the server whose hard disk failed.

Who's is a contraction of who is or who has.
We do not use contractions in Vaadin technical documentation.

"Wi-Fi"

"wildcard"

"will"

Try to avoid using the future form will unless you really are talking about the future.
A common case is when talking about the behavior of software.
For example:

Press OK. A new dialog will open.

If there is no authenticated user, the method will return null.

Instead, write

Press OK. A new dialog opens.

If there is no authenticated user, the method returns null.

"wireframe"

"workspace"

"workstation"

X

"x-axis"

"x-coordinate"

Y

"y-axis"

"y-coordinate"

"YAML"

Do not use the extension .yaml to refer to a file type.

Z

"z-axis"

"z-coordinate"

"zero"

The plural of zero is zeros.

"zip"

Do not use the extension .zip to refer to a file type.