zephyr/doc/collaboration/documentation/simple.rst

.. _simple_english:

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.