| .. _simple: |
| |
| Simple English |
| ############## |
| |
| Simple English is a generic term for communication that emphasizes |
| clarity, brevity and the avoidance of unnecessarily complicated or |
| technical terms. It encourages writers to create content that is clear |
| and appropriate to the audience's reading skills and knowledge. |
| |
| Simple English improves the clarity of procedural technical writing, |
| makes translation easier, and improves comprehension for people whose |
| first language is not English. |
| |
| We do not use controlled language guidelines, which restrict the |
| writer's vocabulary to a list of approved words. Although some |
| preferences are in place. |
| |
| Short Sentences and Paragraphs |
| ****************************** |
| |
| Clear writing should average 15 to 20 words per sentence. This does not |
| mean every sentence should be the same length. Vary your writing by |
| mixing short sentences with longer ones, but stick to the basic |
| principle of one main idea in a sentence, plus one additional point if |
| needed. |
| |
| Similarly, restrict your paragraph length to about six sentences. |
| Remember the basic structure of a paragraph: Introduction, body and |
| conclusion. Both the introduction and the conclusion should be one |
| sentence long. The body of a paragraph should never exceed four |
| sentences. Here less is more. |
| |
| Simple words |
| ************ |
| |
| Choosing simple words increases reader comprehension and reduces |
| ambiguity. Here are some guidelines on making good simple word choices: |
| |
| * Avoid jargon. Jargon is a type of language that is only understood |
| by a particular group of people, such as an industry or a club. You |
| can use jargon when writing for an audience who will understand, but |
| avoid over using it, especially on the general public. |
| * Be consistent. Use one term for each concept or action and use it |
| consistently. Don't use a different term for the same object or |
| action when you refer to it subsequently. |
| * Keep your style plain but avoid dullness. Avoid clichés, idioms, and |
| metaphors. Many of these devices are not easily understood across |
| different cultures and can lead to confusion. |
| * Avoid "fancy" words and phrases. The goal is to get the information |
| across, not to impress the reader with your vocabulary, so avoid |
| bureaucratic, flowery or literary style. Here are some examples of |
| "formal" words to avoid and preferred "informal" alternatives in |
| parentheses: |
| |
| * commence (start, begin) |
| * consequently (so) |
| * in excess of (more than) |
| * in the event of (if) |
| * prior to (before) |
| * should you wish (if you want) |
| * utilize (use) |
| * instance (example) |
| |
| Strong verbs |
| ************ |
| The stronger and clearer you can make your verbs, the more directly you |
| communicate information to your audience. |
| |
| Keep these basic guidelines in mind as you check your verbs: |
| |
| * Use imperatives. |
| * Use active voice not passive voice. |
| * Avoid linking verbs; is, seems, becomes. |
| * Convert weak verbs and nominalizations to strong verbs. |
| * Be concise. |
| * Avoid "there are" and "it is" constructions. .. note:: The following |
| examples offer two versions of the same information. The incorrect |
| version always comes first and is formatted *in italics*. The correct |
| version is comes always second and is formatted **in bold**. |
| |
| Imperatives |
| =========== |
| |
| Commands, officially called imperatives, are the fastest and most direct |
| way of giving someone instructions. Imperatives are an extension of the |
| second-person pronoun you. The word you is implied. |
| |
| Be concise. |
| |
| Example: |
| |
| *I would appreciate it if you would send it to me.* |
| |
| **Send it to me.** |
| |
| |
| Present Tense vs. Future Tense |
| ============================== |
| |
| Use simple present tense instead of future tense for most text. Future |
| tense is acceptable for conditional statements, for example in a |
| caution or a warning. |
| |
| *The system will operate at a nominal temperature of 180 degrees Fahrenheit.* |
| |
| **The system operates at a nominal temperature of 180 degrees Fahrenheit.** |
| |
| Action Verbs vs. Nominalizations |
| ================================ |
| |
| Avoid nominalizations, which are nouns formed from verbs. For example: |
| |
| ===================== ===================== |
| Verbs Nominalizations |
| ===================== ===================== |
| complete completion |
| introduce introduction |
| provide provision |
| fail failure |
| arrange arrangement |
| install installation |
| ===================== ===================== |
| |
| The problem with nominalizations is that they are often used instead of |
| the verbs they come from. Because they are merely the names of things, |
| they sound as if nothing is actually happening in the sentence. Like |
| passive verbs, too many of them make writing very dull and heavy-going. |
| |
| Here are some examples. |
| |
| *We had a discussion about the matter.* |
| |
| **We discussed the matter.** |
| |
| *The blizzard will cause a stoppage of the trains.* |
| |
| **The blizzard will stop the trains.** |
| |
| *IT has completed the installation of the software.* |
| |
| **IT has installed the software.** |
| |
| Infinitives vs. Participles |
| =========================== |
| |
| * Avoid present participial forms and gerunds, words ending in -ing, |
| unless they are part of a technical name. |
| * Use infinitives instead of participials in this type of |
| construction. For example: |
| |
| *There is no way of verifying this.* |
| |
| **There is no way to verify this.** |
| |
| |
| Active Voice vs. Passive Voice |
| ============================== |
| Use active voice whenever possible to show clearly who or what is |
| performing an action. |
| |
| * Active voice follows standard English word order: |
| SUBJECT–VERB–OBJECT (optional). Modifiers come before or immediately |
| following the terms they modify. |
| * Passive voice reverses the order and weakens the verb: OBJECT–be |
| VERB–by SUBJECT (optional). |
| * Writing sentences in the passive voice, we often have to use the |
| verb to be and sometimes the preposition "by". |
| |
| Examples: |
| |
| |
| *A mistake was made.* (By whom?) |
| |
| **I made a mistake.** |
| |
| *The sheriff was shot by me.* |
| |
| **I shot the sheriff.** |
| |
| *Version 2.0 was released in June.* |
| |
| **We released version 2.0 in June.** |
| |
| .. note:: |
| Sometimes it is okay to use passive voice. For example, you may |
| use passive voice to avoid gender-specific pronouns, to avoid |
| blaming someone, or to address situations where the subject, who |
| did the action, is unknown or irrelevant. |
| |
| Noun phrases |
| ************ |
| Avoid long strings of nouns. Even native English speakers might have |
| difficulty determining which term modifies one or another in long |
| strings. |
| |
| Similarly, avoid long noun phrases with multiple adjectives. Try to |
| limit the number of modifiers in any noun phrase to two terms maximum. |
| |
| Often the best way to split up these long noun strings is to separate |
| them into digestible prepositional phrases. This tends to lengthen them |
| but makes them much easier to understand. |
| |
| Examples of some long noun phrases and possible rewording: |
| |
| *Power management mechanism integration policies* |
| |
| **Integration policies for power management mechanisms** |
| |
| *Signal integrity test deck requirements* |
| |
| **Requirements for test desks that measure signal integrity** |
| |
| *Building radon source location method* |
| |
| **Method for locating the source of radon in buildings** |
| |
| *Employee compensation level evaluation procedures* |
| |
| **Procedures for evaluating an employee's compensation level** |
| |
| Pronouns |
| ******** |
| |
| First Person |
| ============ |
| |
| We recommend using we or the Zephyr Project, if you want to sound more |
| formal, to provide an agent, someone who does the action in a sentence, |
| and avoid passive constructions such as "It is recommended...." For |
| example: |
| |
| |
| *5 MB is recommended.* |
| |
| **We recommend 5 MB.** |
| |
| *It is recommend that you set the value as low as possible.* |
| |
| **We recommend setting the value as low as possible.** |
| |
| *This setting has not been validated.* |
| |
| **Intel has not validated this setting.** |
| |
| Second Person |
| ============= |
| |
| Write directly to the reader and use the second-person pronoun "you" |
| rather than "the user". For example: |
| |
| *If the widget is to be compressed....* |
| |
| **If you want to compress the widget...** |
| |
| *If reduced costs are wanted...* |
| |
| *If the user wants to reduce costs...* |
| |
| **If you want to reduce costs...** |
| |
| |
| Third Person |
| ============ |
| |
| Third person pronouns tend to create subject-verb agreement errors |
| because writers often introduce a gender-neutral third person plural |
| they. Rewrite these sentences using a third person plural antecedent. |
| Avoid third person singular pronouns, especially the gender-specific |
| pronouns he and she, and, if necessary, rewrite these sentences using |
| plurals to avoid a gender-specific references in gender-indeterminate |
| situations. |
| |
| The preferred hierarchy of third-person pronoun usage is: |
| |
| *Wrong* |
| |
| *If a user needs to update their account...* |
| |
| Do not use the third person plural for a singular subject. |
| |
| *Avoid* |
| |
| *If a user forgets her password...* |
| |
| Do not force the feminine pronoun set (she) unless there is a specific, |
| approved feminine antecedent or there is some other very strong, |
| circumstantial reason to do so. |
| |
| Acceptable |
| |
| If a user needs to update his account... |
| |
| In traditional English usage, it is acceptable to use the masculine |
| pronoun set (he) when the gender is neutral or indeterminate. |
| This is often the rule in romance languages and other languages. |
| |
| **Preferred** |
| |
| **If users need to update their accounts...** |
| |
| Often the best solution is to use the plural form to avoid pronoun |
| problems. |