Using Simple and Unambiguous Language

When you are writing, reviewing, or editing technical documentation, keep in mind that all Progress Software 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.

In This Article

• Choosing the Appropriate Language
• Examples of Complex, Ambiguous, and Foreign Words

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

Not so good	Much better
a large portion of, a major portion of	most
accomplish	do
additional	more
advantageous	better, useful, easier
alleviate	lessen, ease
as	because
as long as	if
ascertain	learn, make certain
at the present time	now
attempt	try
author (v.)	write, create
by means of	by, with
capability	ability, power
construct, fabricate	make
demonstrate	show
desire	want
despite the fact that	although
discontinue	stop, remove
discover	find, realize
due to	because of
e.g.	for example
employ	use
encounter	meet
endeavor	try
enumerate	list
et al.	and others
etc.	and others, so on
facilitate	aid, help, assist
for the purpose of	for
have the capability	can
hence	so, as a result
i.e.	in other words
in order that, so that	so
in order to	to
in some instances, in some cases	sometimes
in spite of	regardless of, despite
initiate, commence	start, begin
locate	find
majority	most
may	can, might
mitigate	relieve
modification	change
numerous	many
on the other hand	however, by contrast
once	after, when
perform	do
possess	have
present	give, show, tell
prior to	before
require	need
resources	time, money, people
retain	keep
serves the function of	is
since	because
status	state
subsequent to	after
sufficient	enough
terminate	end
through	finished
transmit	send
utilize, employ	use
via	by, through, over
vice versa	and the reverse
voluminous	large
vs.	versus
while	although, whereas