Grammar
Grammar standard
This section contains information on a few common grammar topics.
Here's what you'll find here:
1 Active voice
Use the active voice ("Type ... to start Linuxconf") rather than passive ("Linuxconf can be started by typing ...") whenever possible. Active voice makes for more lively, interesting reading. It is more compelling than passive voice and helps to reduce word count.
This doesn't mean that the passive voice is forbidden. There are situations when using the passive voice is appropriate, such as release notes, technical notes, and similar material.
For example, the sentence, "The Developer Center, a site for reference material and other resources, has been introduced to the OpenShift website." reads better than "The OpenShift website introduces the Developer Center, a site for reference material and other resources." Here, the passive voice is better because the important issue ("The Developer Center") is the subject of the sentence.
You can also use the passive voice to front-load important keywords in key areas of your content, such as the title, heading, or at the beginning of a paragraph or sentence. You need to make these decisions on a case-by-case basis, weighing the importance of front-loading keywords against content that is readable (that is, not awkward sounding).
Consider the following two examples: Example 1.1: Active Voice
"Dutch hosting provider Oxilion launches public cloud service based on Red Hat Enterprise Virtualization." Example 1.2: Passive Voice
"Public cloud service based on Red Hat Enterprise Virtualization launched by Dutch hosting provider Oxilion."
2 Possessives
A possessive indicates that something or someone belongs to a person or thing. Do not use possessives with product names:
Example
Improvement
Microsoft's features help you improve the security of your infrastructure.
Microsoft features help you improve the security of your infrastructure.
3 Sentence structure
A sentence is one complete thought. It expresses something about a subject (a person, place, or thing) and a verb (what the subject is or does).Consider the following points when constructing sentences:
3.1 Sentence length
Try not to pack too much information into one sentence. In technical documentation, try not to exceed 40 words in a sentence. Keep it short.
The following sentence is a bad writing example:
The Start button, which you can find in the bottom left corner of your screen (also activated by the "Windows key" on your keyboard, the one between the Ctrl and Alt keys), provides a central starting point for applications and tasks, and can be customized according to your individual preferences so that it presents menu items relevant to you instead of presenting the standard items that come with the default installation of the operating system, items which, in my opinion, are irrelevant for most users these days who really only need access to an internet browser such as Google Chrome or Mozilla Firefox.
3.2 Preposition at the end of a sentence
Allow a preposition at the end of a sentence to avoid otherwise awkward wording.For example, instead of "Click the workspace to which you want to switch", which can sound stilted, it flows better to use "Click the workspace to switch to".
3.3 Run-on sentences
Two or more complete ideas that are joined without punctuation, or separated only by a comma, create a run-on sentence (also called a fused sentence). The sentence does not have to be long to be a run-on sentence, although the longer the sentence the more difficult it is to read. You can: Separate independent clauses with a period. This creates two sentences from one. Use semicolons to form a compound sentence. Think of a semicolon as an extended breather; it is longer than a comma.
Insert a coordinating conjunction, such as "and" or "but", between the independent clauses to form a compound sentence. For example, "The process starts, but it produces an error." Insert a subordinating conjunction, such as "although" or "because", which forms a compound sentence with a subordinate clause. For example, "Although the process starts, it produces an error.":
Example
Improvement
The CDs both of which belonged to the developers were in the test lab.
The CDs, both of which belonged to the developers, were in the test lab.
The CDs, both of which belonged to the developers, were in the test lab, because they were the only available CDs for the new release, the developers were anxious about keeping them clean. (This sentence exhibits a comma splice which is also often regarded as a run-on sentence.)
The CDs, both of which belonged to the developers, were in the test lab. Because they were the only available CDs for the new release, the developers were anxious about keeping them clean.
3.4 Sentence fragments:
A sentence fragment is an incomplete sentence. For example, "Windows releases no upgrade before its time." is a complete sentence, whereas in "We will release no upgrade. At least, before its time." the second of the two sentences is a fragment. Repair sentence fragments by making them complete sentences.
3.5 Telegraphic style:
Extreme cases of word economy can result in a telegraphic style, omitting words that can clarify the meaning of a sentence, such as articles, prepositions, and verbs used with gerunds:
Example
Improvement
Minor revision - missing element items.
No devices are assigned to the latter connection.
Some further work required to avoid 404s at lower levels of the SDK.
Some further work required to avoid 404 errors at lower levels of the SDK.
3.6 Causative verbs:
Avoid the construction "have something happen". Rewrite to replace "have" with a verb that describes the actual action:
Example
Improvement
The latter connection has no devices assigned.
Minor revision - added missing element items
To have the changes take effect…
To apply the changes…
3.7 The "either-or" construction
Use the "either x ... or y" construction only to refer to a choice between two options, not for three or more options:
Example
Improvement
Scale up by adding more resources, with either more memory, CPUs, or disk space.
Scale up by adding more resources, such as memory, CPUs, or disk space.
3.8 Use of "following"
Use "following" with a noun:
Example
Improvement
Non-privileged users can use the role to configure the following:
Non-privileged users can use the role to configure the following interfaces:
3.9 The "if-then" construction
Generally, follow an "if" statement with a "then" statement.
Example
Improvement
If one service is started, the other is also started.
If one service is started, then the other is also started.
3.10 Including "that" in clauses:
Include the word "that" in clauses unless it results in writing that is too formal or stilted. Including the conjunction "that" makes the sentence easier to translate and improves clarity for readers whose primary language is not English:
Example
Improvement
Verify your directory service is working.
Verify that your directory service is working.
3.11 Use of "this", "that", "these, "those"
Use "this", "that", "these", or "those" followed by a noun. Doing so improves clarity for readers whose primary language is not English, and improves accuracy of translation into other languages where these words differ based on the gender of the noun that they refer to:
Example
Improvement
This causes SSH to lose the recorded identities of the remote systems.
Option 1: This action causes SSH to lose the recorded identities of the remote systems.
Option 2: Consequently, SSH loses the recorded identities of the remote systems.
A site can use these to self-assign a private routable IP address space inside the organization.
A site can use these unique local addresses to self-assign a private routable IP address space inside the organization.
3.12 Verbosity
Avoid unnecessary words. Keep it succinct:
Example
Improvement
The fsck /dev/vdb1 command performs a file-system check on the XFS file system residing on the /dev/vdb1 partition.
The fsck /dev/vdb1 command checks the XFS file system on the /dev/vdb1 partition.
Perform the installation of the product.
Install the product.
3.13 Word order
When two or more correct arrangements are possible, choose the order that creates the least ambiguity. Generally, this is the standard subject-verb-object sequence, with modifiers before or immediately following what they modify:
Example
Improvement
To update the address lists might be your primary concern.
Your primary concern might be to update the address lists.
4 Easily confused words
This section identifies some easily confused words and how to choose the correct term for your situation
4.1 Affect and effect
Each of these words can be used as a verb or a noun, but they are not always interchangeable.
Affectn.
Refers to the emotional impact of an action. Unless you are writing a psychology article, this is unlikely to be the choice for you.v. Means to have an influence on something, or to cause something to change.
Effectn.
Refers to the result of some action. For example, "the team members discussed the effect of the new policy on their working conditions."v. Means to produce a result, or to cause something to happen. For example, "the CEO claimed that the new policy would effect a positive economic outcome."The use of "effect" as a verb is less common than the use of "affect", and there are usually alternatives that are clearer. For example, "the CEO claimed that the new policy would produce a positive economic outcome."
4.2 Assure, ensure, and insure:
These are relatively easy to get right, but here are some quick definitions.
Assurev.
Suggests mental comfort. For example, "I assured my future father-in-law that I would eventually find a job."
Ensurev.
Means to make sure of something, to be certain that something exists or some condition has been met.
Insurev.
Relates to monetary insurance.
5 Contractions and Abbreviations
Contractions make the text more readable, so we encourage you to use them. For example, use "don't", "won't", or "can't".
Abbreviations, instead, make the text less readable. So, we encourage you to replace them. For example, replace "e.g." with "for example", replace "i.e." with "that is", and so on.
5.1 Punctuation
This section contains information on common punctuation topics.
5.1.1 Colons and Semicolons
Current standards allow the use of a colon or semicolon in a range of different circumstances. Some of these are described in the following sections.
5.1.2 To relate clauses
The following sentences show a connection or shared theme between two clauses, or use the second clause to reiterate or amplify the idea in the first clause:
They had been writing code all night: this factor could explain their bloodshot eyes.
They had been writing code all night; this factor could explain their bloodshot eyes.
I spend a lot of money on food; last month, I went out to eat 36 times.
I spend a lot of money on food: last month, I went out to eat 36 times.
The phrase following a semicolon or colon should begin with a lowercase letter, unless it begins with a proper noun. In the case of a colon, use an uppercase letter if the phrase constitutes a complete sentence on its own. Try to limit your use of colons and semicolons. Separate sentences with a period if possible.
5.1.3 To introduce a series
A colon is generally used before a series.
The Triangle Area consists of three cities: Raleigh, Durham, and Chapel Hill.
Do not use a colon if the series is a complement or object of an element in the sentence.
Before going on vacation, be sure to (1) set the alarm, (2) cancel the newspaper, and (3) ask a neighbor to collect your mail.
Use a semicolon to separate items in a series if the items contain commas.
Every day I have coffee, toast, and fruit for breakfast; a salad for lunch; and a peanut butter sandwich, cookies, ice cream, and chocolate cake for dinner.
When a conjunctive adverb (such as however, therefore, otherwise, namely, for example, and so on) joins two independent clauses, use a semicolon before the conjunctive adverb and a comma after it.
I think; therefore, I am.
5.1.4 To introduce a list, command, code block, or procedure
If a list, command, code block, or procedure immediately follows a single stem or introductory sentence, then end that sentence with a colon.If, however, any sentences intervene between the introduction and the next item, then end both the introduction and any intervening sentences with a period instead.In the following example, the related list immediately follows the stem, or introductory sentence, after "as follows". If that sentence instead ends with "the following", then ensure that a noun is used after those words.
The steps for changing directories are as follows:
Open a terminal.
Type
cd Documents/Books.
5.2 Commas
5.2.1 In compound sentences
Use a comma to join clauses in a compound sentence, unless the clauses are short and have a similar theme.
I spent five hours working on this document, but I lost it when my computer crashed.
Do you want to go to the mall and the grocery store with me, or are you going to watch football instead?
You play and I'll sing.
A comma can be omitted from a sentence with several clauses, but only when there is little chance that the sentence could be misread without it.
We played football all afternoon and were completely exhausted but we still stayed up watching movies all night.
That sentence is acceptable, but adding a comma before "... but we still stayed up ..." would provide a pause and avoid the chance of having it read like a run-on sentence.In a compound sentence that contains several short independent clauses, separate the clauses with commas and use a comma before the conjunction.
You need to go to the grocery store for milk, drop off my dry cleaning, and pick up your little sister from soccer practice.
5.2.2 With conjunctive adverbs
When using a conjunctive adverb (such as however, therefore, otherwise, namely, for example, and so on) in a sentence, set it off with commas.
It rained all afternoon. As a result, we canceled our picnic.
The grass, however, stayed dry under the trees.
5.2.3 In adverbial clauses and phrases
If a dependent clause is restrictive (omission affects the meaning of the main clause), do not set it off with commas. If it is nonrestrictive (omission does not affect the main clause), set it off with commas:
I'll go to lunch with you if we can get pizza.
I don't want to go out for pizza, because I had pizza yesterday.
If a dependent clause comes before the main clause, use a comma whether the clause is restrictive or not.
If we get pizza, I'll go to lunch with you.
When I heard the voice on the other end of the line, I was quite surprised.
5.2.4 In adjectival clauses or phrases
An adjectival clause that can be dropped without changing the meaning of the sentence is set off with commas.
The application, which comes with excellent documentation, is used by many graphic artists.
An adjectival clause that cannot be dropped without changing the meaning of the sentence is not set off with commas:
The plan that matters most to us will be easy to implement.
5.2.5 With coordinate adjectives
Separate coordinate adjectives (two or more adjectives modifying the same noun) with commas.
My dog is loyal, obedient, and affectionate.
It was a long, boring meeting.
5.2.5 With series and lists
Separate elements in a series of three or more with commas, including a comma before the conjunction if one is used.
Today I am wearing socks, shoes, pants, and a shirt.
5.3 Parentheses
Parentheses are similar to commas in that they set off information that further explains or enhances a statement. Information that is closely related to the statement should be set off with commas; information that is more incidental should be set off with parentheses.
I tried to get to the elevator before the door shut, but I was too slow.
Most of my favorite authors (Shakespeare, Dickens, Woolf) are dead.
Expressions beginning with "for example", "that is" and so on can be set off with parentheses if they cause a major break in the sentence. If the break is minor, use commas.
He interviewed the biggest stars of the day, namely, Madonna, Johnny Cash, and Jack Nicholson.
Classic works of literature (such as Dickens, Shakespeare, and the Brontes) lined the shelves.
If the contents of the parentheses include at least one complete sentence, the period goes inside the parentheses. If not, the period goes outside.Do not use "(s)" in parentheses to denote a plural. If something can be singular or plural, make it plural:
Example
Improvement
Choose the item(s).
Choose the items.
5.4 Slashes
Avoid the use of a slash character to mean either of two options.For example, instead of "enable/disable", use "enable or disable".Instead of "A and/or B", use "A or B", or "A, or B, or both".1.6.5 Names of Punctuation Marks and Special CharactersUse the names in the following table to refer to punctuation marks or special characters:
Example
Improvement
&
Ampersand
< >
Angle brackets
'
Apostrophe
*
Asterisk
@
At sign
\
Backslash
`
Backtick
{ }
Braces
[ ]
Brackets
^
Caret
✓
Checkmark
:
Colon
,
Comma
"
Double quotation mark
...
Ellipsis
—
Em dash
–
En dash
=
Equal sign
!
Exclamation point
/
Forward slash
>
Greater than symbol
-
Hyphen or minus sign
<
Less than symbol
#
Number sign; use hash to refer to a hashtag in social media
( )
Parentheses
%
Percent sign
.
Period; dot (when not referring to punctuation)
+
Plus sign
?
Question mark
;
Semicolon
'
Single quotation mark
~
Tilde
_
Underscore
6 Pronouns and gender references
Do not use gender-specific pronouns in documentation, except to refer to a specific named user, such as in a case study. It is easier to read a sentence that uses "they" and "their" rather than "he/she" and "his/hers". It is acceptable to use "they" to refer to one person, with a plural verb.
Usually, when giving instructions, use the imperative mood or use "you". In more general explanations, you can use "users" or "new users". Do not use "one" in place of "you" when writing technical documentation, because it is too formal. Do not use "it" to refer to a person. Avoid first person "I, we, our". Use the second person "you" whenever possible.
7 Tense
Avoid future tense (or using the term "will") whenever possible. For example, future tense ("The window will open ...") does not read as well as the present tense ("The window opens ..."). Remember, the users you are writing for most often refer to the documentation while they are using the system, not after or in advance of using the system. Use simple present tense as much as possible. It avoids problems with consequences and time-related communications, and is the easiest tense for translation.
Last updated