- adverb phrases
- ampersand ("&")
- angle brackets
- apostrophe (’)
- colon (“:”)
- colloquial expressions
- comma splice
- control-key combinations
- countable (and uncountable) entities
- cultural references
- dangling participles
- dash (“–”)
- definite article (“the”)
- double quotes (“)
- em dash ("—")
- en dash ("–")
- exclamation mark ("!")
- future tense
- hyphen (“-”)
- indefinite article
- introductory clauses
- Latin abbreviations
- menu header
- method names
- multiplication sign
- non-breaking space
- nouns as descriptors
- number sign
- Oxford comma
- passive voice
- phrasal verbs
- product names
- proper nouns
- quotation marks
- relative clauses
- semi-colon (“;”)
- single quotes (‘ ’)
- slash (“/”)
- split infinitive
- time clauses in the future
- Vaadin versions
Do not terminate abbreviations with a period if the last letter of the unabbreviated form is included in the abbreviation. For example:
M. Duval [abbreviation of the French word monsieur]
and so on.
In general, plurals of abbreviations are formed by adding a lowercase s.
Do not use apostrophe s (’s) for this purpose.
[abbreviation for standard operating procedures; not SOP’s]
Admonition blocks such as
[WARNING] can be used to emphasize important issues.
However, do not overuse them, as this can interfere with the flow of the text .
There should be no more than three admonitions on a page.
Use a descriptive title for admonitions.
.Do not overuse admonitions [WARNING] Overusing admonition blocks interrupts the flow.
Do not overuse admonitionsOverusing admonition blocks interrupts the flow.
If you begin a sentence with an adverb phrase, place a comma after the phrase.
Unfortunately, we cannot reproduce the bug.
As you can see, the screen layout is logical.
This morning, I spoke to our customer services manager.
Do not use the ampersand character in place of and in general text, unless space is limited.
In general text,the name for the < and > characters is angle brackets.
In other contexts, the same characters are known as the less than and greater than symbols.
The apostrophe has a specific function: to indicate when one or more letters have been omitted. For that reason, it is used in contracted forms of verbs.
In general, in our technical documentation, we avoid using contracted forms. They are correct English, but they are more appropriate to less formal writing.
Nevertheless, to show the function of the apostrophe in contractions in general, here are some examples:
I am → I’m
[The letter a is omitted.]
She is → She’s
[The letter i is omitted.]
They are not → They aren’t
[The letter o is omitted.]
In some cases this logical system of contraction has been adapted, by convention and usage. For example:
He will not → He won’t
[A little illogical, but it is the accepted contraction.]
We shall not → We shan’t
[And not, for example, sha’n’t.]
The other standard use of the apostrophe in English is to indicate possession.
In fact, this has its logic. In Old English, the possessive case of a noun was formed by adding -es to it.
In modern English, the e has been dropped from that suffix; this omission is now marked by that apostrophe.
The possessive form of a single noun is formed by adding ’s. For example:
The developer’s guide
The boss’s office
The possessive of a plural is formed by the following process:
write the ordinary plural form
if that plural form already ends in s (the commonest case), place the apostrophe after that s
in the few irregular cases where the plural form does not end in s (for example, men, women, children, sheep), add ’s, as for a single noun
The employees’ salaries
The bosses’ salaries
The women’s records
The mice’s tails
For when to form a possessive using an apostrophe, and when to use of, see possessive.
Consider this sentence:
The CEO, Nick Smith, spoke to a company employee.
In this sentence, The CEO and Nick Smith identify the same entity (in this case, a person). In other words, Nick Smith is another name for the CEO.
In the terminology, the phrase Nick Smith is "in apposition" with the CEO.
Notice that the phrase that is in apposition is delimited by commas.
Now, consider this sentence:
The CEO, Nick Smith, spoke to company employee Susan Rae.
In this case, company employee and Susan Rae do not identify the same entity.
It is likely that there is only one Susan Rae in this context, but there are, no doubt, many company employees. In other words, Susan Rae is not another name for company employee.
Hence, Susan Rae is not in apposition with company employee and, for that reason, is not delimited by commas here.
Let’s look at an example that is more relevant to the context of technical documentation.
Here is some information about the parameters of a method.
The method takes a single parameter:
The method’s parameter,
duration, specifies the time in milliseconds that the animation should run.
Here, as there is only one parameter, the method’s parameter and duration refer to the same entity. Duration is in apposition with the method’s parameter, and so is delimited by commas.
Now, here is some similar information but, this time, the method takes more than one parameter.
The method takes two parameters:
duration specifies the time in milliseconds that the animation should run.
Here, parameter and duration do not mean the same thing. For this reason, duration is not in apposition with parameters, so it is not delimited by commas.
Missing and misused articles (a, an, the) are a very common problem, especially for speakers of languages which do not have articles, such as Finnish, Russian, and Japanese.
Although the basic concept of articles is quite simple, there are some special cases and exceptions that can complicate the issue. You may find the following useful:
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.
In some articles, it may be necessary to show the author.
Authors can identify themselves after the section title as follows:
[.author] [name]#Marko Grönroos# <firstname.lastname@example.org>
For section, this should be in the overview.
Note that for non-ASCII characters, you should use HTML character entity markup.
The [ and ] characters are called brackets or square brackets.
For the ( and ) characters, see parentheses.
We should capitalize only when there is a good reason for doing so. Otherwise, capitalization can creep into lots of areas where it has no place.
One situation where this often happens is in the context of common abbreviations and acronyms.
We might think that, because capital letters are used in an acronym, we should also use capital letters when the term is written out in full.
This is usually not the case, unless the term is a proper noun. (See proper nouns.)
command line interface
software as a service
Java Development Kit [proprietary name]
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 it is this… or and this 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.
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.
Avoid using colloquial expressions in Vaadin technical documentation, as they may be unfamiliar to people whose native language is not English.
Consider the following (incorrectly punctuated) sentence:
You should never divide by zero, this will cause a runtime error.
In this example, we have two complete clauses, as each one has a subject and a finite (full) verb. It is an error to join the two clauses with a comma. This error is often called a comma splice. (Splice means join.)
We have several options to rectify this error. The simplest option is to make each clause a sentence on its own:
You should never divide by zero. This will cause a runtime error.
This solution is grammatically correct. However, it does not show the logical connection between the two clauses. A better option would be to use different punctuation. A semi-colon would serve the purpose:
You should never divide by zero; this will cause a runtime error.
Unlike a comma, a semi-colon can be used to join two complete clauses. Moreover, it implies a logical connection between them, although the specific logic is left to the reader’s interpretation. (See semi-colon.)
Another option would be to use an appropriate conjunction. As its name suggests, a conjunction is a joining word. Some common conjunctions are: and, but, or, because, as and so. Conjunctions often imply some kind of logical connection between the clauses that they join.
In our example, we want to express a concept of causation. Because and as would be suitable options:
You should never divide by zero, because this will cause a runtime error.
You should never divide by zero, as this will cause a runtime error.
Although the meaning of these two versions is the same, in fact, by convention, we use as more often than because to express this kind of causation. Consequently, the second version is the best of the options that we have discussed.
Avoid congratulating the reader, for example, for successfully working through a tutorial and completing the process that the tutorial describes. It sounds patronizing.
Contractions (or "contracted verb forms") are those where one or more letters are omitted. For example:
She’s on her way to the meeting. [She’s is a contraction of she is.]
They’ll be here on Friday. [They’ll is a contraction of they will.]
In general use, contractions are perfectly acceptable and correct. In fact, using contractions can help to make a non-native speaker’s English sound much more natural.
However, contractions are not generally appropriate in formal contexts, such as academic works and legal documents. We have made the decision not to use contractions in our technical documentation, perhaps sacrificing a little friendliness of tone in the interests of simplicity of language.
If your audience includes macOS users, provide the appropriate key-naming terminology. Spell out Control and Command, rather than abbreviating them. For example:
Press( on Macintosh) to save.
Some entities have the characteristic of existing as separate objects, such that we can count them.
For example, books are objects that exist separately from each other, so that it makes sense to talk about one book, two books, and so on.
We call this category of objects countable.
We view some other entities as existing in bulk, as amounts of something, rather than a number of separate objects that we can count.
For example, we apply the label air to a contiguous body of gaseous substances. It does not usually make sense to talk about one air or two airs.
The same applies to entities such as sugar, water and aluminum.
We call this category of entities uncountable.
From the point of view of grammar, it is important to consider whether or not some entity is countable.
For example, the indefinite articles, a and an, convey the meaning of one of something.
Hence, it makes sense to use them with countable nouns, but not with uncountable ones.
There is no meaning in the phrases an air or a water.
Similarly, countable nouns, by definition, can be plural.
Uncountable nouns, again by definition, cannot be plural.
However, there is a small trap here.
Many nouns cannot be categorically defined as either countable or uncountable; it depends on their meaning in the given context.
For example, time as a concept is uncountable.
It would not make sense to say, for example:
I’m sorry I haven’t got a time to talk to you now.
On the other hand, time is countable when it means an occasion or a period.
I remember a time when 1 Mbyte was a lot of memory.
How many times have I asked you not to do that?
Consider, too, the difference between:
I don’t like coffee.
Would you like a coffee?
How many coffees have you had this morning?
Place currency symbols before the numeric amount. For example:
In general, in the absence of other information, we assume that the dollar ($) symbol indicates US dollars. It is not necessary to specify this.
However, where it is required to distinguish between dollar currencies of different states, it should be written as in the following examples:
There is no hard-and-fast rule for forming country codes in this context. Just make sure that it is clear which country is being referred to.
Participles are formed from verbs. Present participles end in -ing; past participles often end in -ed, though there are many irregular forms. Some examples:
Participles are often used as convenient concise forms. For example:
Being the project leader, Hannah Jones chaired the meeting. [A more concise form of: As she is the project leader, Hannah Jones chaired the meeting.]
I was given a spec written on the back of an envelope. [An alternative form of: I was given a spec that was written on the back of an envelope.]
Having caught a terrible cold, I phoned my colleagues to postpone the meeting. [In other words: As I had caught a terrible cold, I postponed the meeting.]
Participles can work well when used in this way, but we need to be careful that our sentence is unambiguous. Consider the last example again:
Having caught a terrible cold, I phoned my colleagues to postpone the meeting.
Who had caught the cold? Was it me or was it my colleagues? Clearly, it was me, but how do we know this? We know because we assume that the next noun phrase after the participle clause indicates the person or thing that the participle refers to.
Look at these similar sentences:
Being corrupt, the file was rejected. [Since the next noun phrase after the participle phrase is the file, it is clear that it is the file that is corrupt.]
Being corrupt, I rejected the file. [In this case, basing our understanding purely on the word order, we might interpret this to mean that I am the one who is corrupt.]
In most cases of such poorly chosen word order, we can probably guess at the intended meaning. However, our goal is that our readers should correctly interpret our material on the first reading.
When the structure of the sentence leaves it unclear to whom or what the participle refers, this is called a "dangling" or "unrelated" participle.
Here are some other examples of poorly chosen, and hence distracting, word order, with some suggestions for improvement:
"Dangling participle" version
Being a public holiday, the office was closed.
As it was a public holiday, the office was closed.
Having crashed three times in one week, we decided to replace the server.
As the server had crashed three times in one week, we decided to replace it.
In our documentation, we use the format
<month> <day number>, <year>. We do not use the ordinal abbreviation suffixes -st, -nd, -rd or -th.
Nor do we write the word the between the month name and the day number.
June 15, 2020
May 1, 2022
Avoid expressing dates using variations of the mm/dd/yyyy or dd/mm/yyyy formats. There are different conventions for these formats around the world, so that the possibility of confusion and misunderstanding is high. Instead, write out dates using month names, as described earlier.
Write out the days of the week in full, if space allows this. Otherwise, abbreviate the names to three characters, as follows:
|Day||3-letter abbreviation||2-letter abbreviation|
In US English, a pair of em dashes (so called because they have the same width as the letter M) are used to indicate a fragment of text in parenthesis. The pair of em dashes imply a more significant break in the structure of the sentence than one marked by a comma or brackets. There should be no space either before or after an em dash. For example:
The tool does not fix the bug—if only it were that simple—but it does help you to identify its location.
You can use a dropdown or a combo—personally, I prefer the latter—but, either way, the user needs to be able to select from the available options.
A single em dash can be used to add an afterthought or aside. For example:
You can use whichever IDE you prefer—it is entirely up to you.
Make sure your code is well commented—you will thank yourself when you revisit it six months later.
Avoid using the em dash too much; it can quickly become distracting and even irritating. Very often, a comma or semi-colon is a more appropriate choice of punctuation, especially in more formal writing, such as technical documentation. The two previous examples could also be written as:
You can use whichever IDE you prefer; it is entirely up to you.
Make sure your code is well commented; you will thank yourself when you revisit it six months later.
Use the emphasis styles, such as
[classname]#ClassName# emphasis for class names and
[methodname]#methodName()# for methods.
|Style Element||AsciiDoc Example Code||Result|
The en dash (so called because it has the same width as the letter N) is commonly used to indicate a range of values. When used in this way, it is not preceded or followed by a space. For example:
Select a number in the range 0–255.
The parameter should be a string of 8–10 characters.
The licence enables you to use the software on 1–3 computers.
He was chief designer (2003–9), and subsequently CEO of the company (2009–12).
The office is open Monday–Friday.
We can also describe ranges by using the words from and between. These forms should not be mixed with the en dash. Use one form or the other, but not both. For example:
You can use the licence on between 1 and 3 workstations.
[Not between 1–3 workstations.]
The parameter should be a string of from 8 to 10 characters.
[Not a string of from 8–10 characters.]
The euro symbol (€) is represented as
€ in AsciiDoc.
In amounts of money, place the euro symbol immediately before the numeric quantity, in the same way as for, for example, the dollar or pound symbol.
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.
You should use title or headline case for all headings and chapter, section, or sub-section titles.
= Style Guidelines for Vaadin Documentation
For a detailed description of capitalization rules, see for example:
Rules for Capitalization in Titles of Articles: Your Dictionary
There is often confusion about whether or not to use a hyphen in compound words (such as start-up and onboarding) and words that include a prefix (such as presales and multifactor). English has no hard-and-fast rules about this; it is simply a question of accepted usage.
In general, use the Merriam-Webster online dictionary as a guide. If the full compound word or prefixed word exists in the dictionary, use the form that the dictionary gives. If the full compound word or prefixed word does not exist in the dictionary, use a hyphen. For example:
[This is the form given in the dictionary.]
[This is the form given in the dictionary.]
log-in (noun) [Neither log-in nor login is given in the dictionary, so use a hyphen.]
Sometimes, we want to mention a series of items, all hyphenated on the same base word. In such cases, we can reduce repetition by applying distributed hyphenated descriptive words to the base word. For example:
The device used a combination of first-generation and second-generation chips.
[OK, but repetitive.]
The device used a combination of first- and second-generation chips.
In general, use a hyphen in compounds formed from an adverb and an adjective, in order to avoid ambiguity as to which word the adverb qualifies. For example:
I am grateful to my hard-working colleagues. Not hard working colleagues.
This benefits low-paid employees. Not low paid employees.
However, do not use a hyphen when the adverb ends in -ly. In these cases, there is no ambiguity concerning which word the adverb applies to. For example:
The technology is a closely guarded secret. Not closely-guarded secret.
This benefits poorly paid employees. Not poorly-paid employees.
See "a" / "an"
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.
An inline list should be introduced by a colon. Items in the list can be separated by commas. However, in cases where items in the list themselves contain commas, it is better to use semi-colons as separators, in order to avoid confusion. For example:
This curry has three vital ingredients: onion, potato, and spinach.
This curry has three vital ingredients: onion, which should be roughly chopped; potato, which should be diced; and fresh spinach leaves, which should be thoroughly washed before use.
If an AsciiDoc file is intended to be rendered as a section, a page, or tab, it must have a header block. This is used to build the menu in the documentation website.
--- title: Title of the article order: 4 layout: page ---
The title to be displayed in the menu. The title should be same as the title of the article, but can be a shortened version to keep the menu more tidy.
Order number in the menu. If articles are reorganized, the order numbers may need to be reorganized, too. It is good practice to make them multiples of 10 or 100, in order to leave space to add new articles without having to renumber all the others.
The layout can be either
tabbed-page. In a tabbed page, the sub-articles are displayed in tabs rather than in the menu. The default tab content comes from the
Sets the tab title in
tabbed-pagepages. It should be kept short.
Use empty parentheses at the end of method names to denote that they are methods. In general, do not list parameter types for methods, unless this is required in order to indicate a specific version of a method. It may also be necessary to specify a parameter when it is relevant in the context. For example:
setEnabled(false) to disable it.
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.
If you need to show the multiplication sign, use × (
×), not the letter x.
One case for using the multiplication sign is to refer to dimensions.
There should be a non-breaking space on either side of the multiplication sign.
The image size should be at least 150 × 150 pixels.
[That is, 150 × 150 pixels.]
In code, you obviously need to use the symbol that is required by the language you are using, which is generally the asterisk character (*).
Use a non-breaking space to prevent the browser from splitting terms in a way that could cause confusion for the reader. Some examples are:
between a number and its units
between numbers and words that define a date
between a person’s title (Ms, Dr, Prof.) and their name
between words separated by a slash ("/") character
A non-breaking space can be written in AsciiDoc as
English is very versatile in allowing nouns to be used as if they were adjectives. For example:
Please close the office door quietly.
Select your preferred keyboard layout.
Bear in mind that when nouns are used like adjectives in this way, they are almost always used in the singular form, not plural. For example:
She is the manager of a shoe shop. [Not a shoes shop.]
This is the responsibility of the microchip manufacturer. [Not the microchips manufacturer.]
Do not use the # character to indicate a number. For example:
See item #3. *[Instead, write See item number 3.]
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.
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
In technical documentation, we very often want to describe the procedures that are necessary in order to perform some task. Such procedures usually consist of a series of steps.
In most cases, we start with a top-level sentence. For example:
Create a new project as follows:
To create a new project, follow these steps:
Do not start with an incomplete sentence at the top-level which is then completed by the text of each step. This structure obliges the reader to keep the top-level text in mind in order to interpret the subsequent text correctly. For example:
To create a new project, you must:
[Avoid beginning with an incomplete sentence which is completed by the text of subsequent steps.]
Make sure you have installed the plugin…
Create a new app…
Use parallel structures in the steps that make up the procedure. In other words, structure each step in a similar way to the others.
Product names, such as List Box, should be capitalized as is usual for proper nouns, not as if they were class names. Use the class name if you are referring specifically to a class. For example:
ListBox extends ListBoxBase.
See the specific entries for each punctuation mark; for example, “commas”, “quotation marks”, etc.
In general, when you want to put text in quotation marks, use double quotation marks (" "). Avoid using single quotation marks (' '), unless, of course, it is required by some code syntax.
Relative clauses allow us to give more information about a person or thing that we mention in a sentence. For example:
Instead of saying: I asked Linda Johnson. She works in the same office as me,
it is neater to say: I asked Linda Johnson, who works in the same office as me.
They are called "relative clauses" because they relate to some entity in the main clause of our sentence. The word that links the relative clause to the main clause is often a "W" word, such as which, who, where, when, or whose. The word that is also often used as the linking word. For example:
The software is written in Java, which is our preferred language.
Jean Reboulet, who led the design team, attended the meeting.
The conference was held in San Francisco, where the company has its headquarters.
We recommend performing full backups at the weekend, when the system is less busy.
We contacted Sandra Stein, whose team maintains the library.
This is the team that maintains the library.
We need to be aware that there are two kinds of relative clause: defining and non-defining.
Why is this important? It matters because it has an impact on the punctuation we need to use, and also on the sentence structure.
A defining relative clause, as the name suggests, defines an entity in the main clause. It gives us essential information in order to identify the person or thing that was mentioned. In other words, without the information in this clause, our sentence would not have the same meaning and might not even make sense at all. For example:
This is the bug which our testing team reported.
[The relative clause is essential in order to understand which bug is being talked about.]
The place where you parked your car is private property.
[The relative clause identifies the place that was mentioned.]
Every page should have at least one screenshot. There should at least be a screenshot in an introduction or overview section.
The basic structure of a new section file is as follows:
--- title: Title of the section order: 4 layout: page --- [[thechapter.thefeature]] = Fine Feature [.author] [name]#Marko Grönroos# <email@example.com> The Fine Feature is a feature of a feature... [[thechapter.thefeature.basic-use]] == Basic Use
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.
The infinitive of a verb is the form that includes the particle "to". Examples of infinitives are to have, to hold, and to program.
Traditionally, it was considered bad style to "split" the infinitive by placing an adverb between the particle and the verb. For example:
It is necessary to fully understand the process before starting. [Instead of, for example, to understand the process fully.]
We had to completely rebuild the library. [Instead of, for example, to rebuild the library completely.]
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 prioritise simplicity, clarity, and accuracy at all times, even if it means we have to compromise on elegance.
Use the ratio character ("∶",
∶) as the delimiter in times, rather than a standard colon.
The difference is that the ratio character is vertically centered on the line, whereas the colon character is anchored to the baseline.
The seminar begins at 11∶00 UTC.
[Not 11:00 UTC.]
We often use time clauses to refer to some time in the future. Such clauses may begin with when, while, until, as soon as, before, and after. In English, we generally use a present or present perfect tense in this type of clause, in spite of the fact that it refers to a future time. The remainder of the sentence may use any appropriate future form, or an imperative (instruction) form. For example:
As soon as you get to the office, call me. [Not As soon as you will get…]
While I am in Scotland, I’ll visit Edinburgh Castle. [Not While I will be in Scotland…]
When you have finished that work, you can start the next task. [Not When you will finish… or When you will have finished…]
The character "_" is called the underscore character.
You can avoid formatting problems in AsciiDoc by using the
_ entity reference.
There is a space 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.