Using Simple and Unambiguous Language

When you are writing, reviewing, or editing technical documentation, keep in mind that all {{site.ps}} content targets an international audience.

This audience requires the use of simple, objective, non-ambiguous language which translates well and does not provide room for interpretation.

Choosing the Appropriate Language

• Use common American English vocabulary. Avoid foreign words or words of foreign origin.

  Not that good	Much better
  via	through or over (Non-native speakers might not be aware of what "via" means.)

• Use simpler and shorter words and phrases.

  Not that good	Much better
  a multitude of	many ("A multitude of" increases the text length and might reduce the text readability.)

• Use non-ambiguous words and phrases.

  Not that good	Much better
  since	because (Non-native speakers might interpret "since" as an expression of time rather than reason.)

• Use correct and consistent terminology even if this might lead to repetition of terms in a sentence or a paragraph. Avoid coining new terms.

• Use very specific words and phrases and avoid generalization.

  Not that good	Much better
  Specify your login credentials.	Type your login credentials. ("Specify" is a term which is correct but does not provide any meaningful information.)

• Use objective language. Keep in mind that users read the documentation for accurate and objective information on which to base their decisions, not for evaluation, opinions, or artistic value.

  • Do not use qualifications such as "good", "best", "worst", and so on.

    Not that good	Much better
    Apache Cordova is the best JavaScript framework for mobile development.	Write "Apache Cordova is a JavaScript framework for mobile development." Provide objective reasoning with which to persuade your users that Apache Cordova is the best.

  • Do not use slang, jargon, humor, sarcasm, colloquialisms, idioms, emoticons, and metaphors.

    Not that good	Much better
    Apache Cordova is a total pain.	Write "Using Apache Cordova might pose several challenges." Provide objective reasoning as to why your users might consider choosing an alternative framework.

• Avoid using the same word for different parts of speech. In particular, avoid using as nouns or adjectives words that primarily function as verbs. Examples of verbs commonly misused as nouns are: "configure", "compile", "debug", and "fix".

  Not that good	Much better
  during the install	during the installation ("Install" is a verb used as a noun and might not be translated properly during localization.)

• Avoid using Latin abbreviations and words where American English alternatives exist. Although the Latin abbreviations are almost universally known, they might not translate well

  However, if you are space-constrained (for example, in a table cell), you can use the Latin abbreviations. When using "e.g." or "i.e.", put a comma before and after them.

  Not that good	Much better
  i.e.	in other words
  etc.	and so on

• Avoid using generic phrases like "there is" and "there are". Such phrases serve a grammatical function but have no real meaning and add unnecessary fluff. Rephrase the sentence and find a better subject and a better verb.

  Not that good	Much better
  There is a set of binaries built against .NET Core & .NET Standard, which you can reference in the application.	In the application, you can reference a set of binaries built against .NET Core & .NET Standard.
  There are six sites that offer this functionality—Facebook, Twitter, Google, LinkedIn, Yammer, and Pinterest.	Six sites offer this functionality—Facebook, Twitter, Google, LinkedIn, Yammer, and Pinterest.

• Avoid culture-specific references that might not be widely understood, such as holidays and celebrations, monetary units, and phone number and address formats.

  Not that good	Much better
  released on Independence Day	released on July 4 (Users might get confused which Independence Day you are referring to. Most nations in the world celebrate their own Independence Day and it might not necessarily coincide with July 4.)

• Avoid using symbols instead of words in running text, even if you are space-constrained.

  However, if you need to convey the original spelling of a trademark, UI element, or a direct quote, you can use symbols instead of words.

  Not that good	Much better
  (For implying "and".) ampersand (&) or plus sign (+)	and

Examples of Complex, Ambiguous, and Foreign Words