Ubuntu Wiki

It is important to ensure the accuracy of the spelling, punctuation, and grammar used in documentation which you write. Adhering to the guidelines given here should ensure consistent use of spelling and grammar across all of the Ubuntu documentation. Such consistency gives the documentation a professional feel. Also, following these standards helps make the translation process easier.

Grammar and English

Terminology may seem tedious to learn. However, to avoid confusion and ensure that your writing is clear and understandable to your audience, you are encouraged to read the following sections.

Parts of A Sentence

Subject and Predicate

A sentence has two main parts: a subject and a predicate. The subject is the person or thing that you are talking about. The predicate is what you are saying about the subject. Without a subject and predicate, there is no sentence.

Clauses

A clause is a part of a sentence with a subject and a verb. There are two types of clauses: main (independent) and subordinate (dependent). A main clause could stand alone as a sentence. For example, in the sentence "Vim is a text editor; it is very well known," both "Vim is a text editor" and "it is very well known" are main clauses because they could both be sentences.

A subordinate clause has a subject and a verb, but it could not stand alone as a sentence. For example, in the sentence "Vim is a powerful text editor because it offers many tools," the clause "Vim is a powerful text editor" is an independent clause. The clause "because it offers many tools" is a subordinate clause.

Clauses are important because they dictate punctuation. A sentence must have at least one main clause. If it does not, it is a sentence fragment.

If a sentence is composed of only one main clause, no additional punctuation is needed.

A sentence composed of two main clauses must be separated in one of three ways.

1. They could be separated by a period.

   • Wrong	Vim is a text editor it is very well known.
     Wrong	Vim is a text editor, it is very well known.
     Correct	Vim is a text editor. It is very well known.

2. You could also use a semicolon. Note that a semicolon can only be used when the clauses are connected and are of equal importance.

   • Wrong	Vim is a text editor it is very well known.
     Wrong	Vim is a text editor, it is very well known.
     Correct	Vim is a text editor; it is very well known.

3. A coordinating conjunction could be inserted. The common coordinating conjunctions are FANBOYS, an acronym meaning "for", "and", "nor", "but", "or", "yet", and "so". When using a conjunction, a comma should usually be inserted before the conjunction. However, the comma can be omitted if the clauses are very simple.

   • Wrong	Vim is a text editor it is very well known.
     Wrong	Vim is a text editor, it is very well known.
     Correct	Vim is a text editor, and it is very well known.
     Correct	Use a terminal and use a text editor.

In the case of both main and subordinate clauses in the same sentence, insert a comma after the subordinate clause if it comes before the main clause. You can also insert a comma if the subordinate clause comes after the main clause.

• Wrong	Though it lacks a good text editor emacs is a powerful operating system.
  Correct	Though it lacks a good text editor, emacs is a powerful operating system.
  Correct	Emacs is a powerful operating system but it lacks a good text editor
  Correct	Emacs is a powerful operating system, but it lacks a good text editor

Note that "however" is not a coordinating conjunction.

• Wrong	Emacs is a powerful operating system however it lacks a good text editor
  Wrong	Emacs is a powerful operating system, however it lacks a good text editor
  Wrong	Emacs is a powerful operating system, however, it lacks a good text editor
  Correct	Emacs is a powerful operating system; however, it lacks a good text editor
  Correct	Emacs is a powerful operating system. However, it lacks a good text editor

Common Errors

Run-On Sentences

Do not use run-on sentences. Run-on sentences are two main clauses that run together into one sentence and are separated by a comma. You can correct a run-on sentence in various ways.

• Wrong	There are quite a few terminal-based editors available in Ubuntu, popular ones include VIM and Emacs
  Correct	There are quite a few terminal-based editors available in Ubuntu. Popular ones include VIM and Emacs.
  Correct	There are quite a few terminal-based editors available in Ubuntu; popular ones include VIM and Emacs.

One Topic Per Paragraph

Each paragraph in your document should address one topic. If you move to a new topic, begin a new paragraph.

Punctuation

Much of this section may be obvious to most people. However, it is important to clarify punctuation conventions to ensure that they are applied consistently across all documents. In addition, limits on the use of certain punctuation marks are imposed in order to ease document translation.

Apostrophe

1. The apostrophe is normally used in forming contractions. Avoid using contractions in technical documents that will be translated into languages other than English.
2. Avoid using the apostrophe to indicate possession because it can cause problems when your text is being translated into a different language. Instead, rework the sentence so that an apostrophe is not needed.
3. Do not use the apostrophe to form plurals of acronyms.
4. The apostrophe can be used to form plurals in certain cases where the lack of an apostrophe may cause confusion. For example, "1's and 0's"

Colon

1. You can use a colon after the words "following" or "follows." For example, "Documentation Team members need to install the following packages: docbook, docbook-xsl, and bazaar."

2. Make sure that text preceding the colon is a complete sentence or a noun phrase.
3. Use a colon after introductory text. For example, "You have only one option: restart the computer."
4. Do not use a colon in headings or at the end of a procedural heading.
5. Do not use a colon in a list that is introduced by "are" or "include."

Comma

The rules for comma use in normal prose are numerous and complicated. However, in a technical document intended for translation, sentences will tend to be shorter and simpler than in normal prose. As a result, comma use will also tend to be limited and therefore only some of the major points are covered here.

1. Use the series comma. The series comma is the comma before the word "and" in a list of three or more words or phrases.
2. Use a comma to set off "for example" and similar words and phrases such as "namely" and "that is." You can find many examples of this type of comma use in the style guide.
3. Use the comma after introductory phrases and clauses.

Hyphen

1. Use a hyphen in compound modifiers preceding a noun. Example: "Evolution is an end-user application."
2. Use a hyphen in spelled-out fractions, unless the fraction is at the start of a sentence. Example: "Well-written documentation is one-half of a successful software application."
3. Use a hyphen in compound words formed with "better", "best", and "well", unless they are already modified. Example: "Subversion is a well-known version control system. It has very well written documentation."

Parentheses

1. Use parentheses around abbreviations and acronyms that you will use later. Example: "The Ubuntu Documentation Project (UDP) is an important part of the Ubuntu Linux distribution."
2. Do not use parentheses to set off an explanation or an aside. For example, do not write a sentence (like this one) that uses parentheses in this manner.

Period

1. Use a period to end sentences.
2. End abbreviations with a period. For example, "abbrev.", "Mr.", and "Ms.".
3. Use a period at the end of each step in a procedure.
4. In lists, use a period only if the list items are complete sentences.

Quotation Marks

1. Use quotation marks around material that is repeated verbatim from another source, when the length of the copied material is such that it can be included "inline" with the paragraph.
2. Use quotation marks around letters, words, or phrases that you want to emphasize without using italics or bold text.

Semicolon

A semicolon can only be used to join two independent clauses when the clauses are connected and are of equal importance. The semicolon is frequently misused, so it is best to avoid semicolons. A sentence with a semicolon can usually be split into two or more sentences. Splitting the sentence will make it easier to read and translate.

Spelling

American English

Use standard American English spelling in all Ubuntu English language documents.

Dictionary for Spell Checking

There is a great deal of agreement among American English dictionaries when it comes to spelling. For the purposes of Ubuntu technical documents, you can use any American English dictionary that is convenient. You can use the built-in spell checker of whatever editor you are using, provided that it is set to American English. Places where there are conflicts (such as "email" versus "e-mail") are handled by the word list.

If you find a spelling conflict that is not in the word list, please let us know what the word is along with your recommendation for the version to use. There is a list of online and printed dictionaries in the Reference Materials section.

Compound Words

In technical documentation, two-word compounds tend to get converted over time, first into hyphenated compounds and then into single word compounds. For example, "on line" became "on-line" and is now gradually becoming "online". In general, use the one-word compound for Ubuntu documentation. However, there are several exceptions to this rule. If you are not sure of a particular word, check the word list.

CategoryDocteam