Content for a global audience
As a global software development firm, Pega creates products and documentation for an audience that includes our own worldwide sales force, as well as the various support teams and engineering labs that Pega maintains around the world. Therefore, we must ensure that all of our writing is clear, concise, and grammatically correct. Everyone then has a better chance of understanding our meaning, whether they are English native speakers, non-native speakers, translators and interpreters, or even translation software.
The clarity and ease of comprehension of our writing directly equates to client satisfaction, and also means that future changes to our documentation and interfaces can be implemented smoothly and consistently. The best way to achieve this standard is to always write with a global audience in mind. Apply the following strategies for writing for a global audience along with the advice in the rest of the Guidebook to ensure that we maintain a consistent approach to our writing at all times.
Some of the basic guidelines for good technical writing coincide with the requirements for writing for a global audience:
- Keep sentences as short and simple as possible (around 25 words or fewer, with commas between clauses). For more information, see Creating clear and consistent content and Punctuation guidelines.
- Avoid ambiguity and vagueness. Ensure that every action has an object, with no
false subjects or
naked this. For more information, see Grammar guidelines.
- Use technical terms only if necessary and appropriate. For more information, see Tone, voice, and terms to avoid.
- Use relevant, Pega-specific examples whenever possible. For more information, see Pega-specific references.
- Write with the appropriate tone (no jargon, idioms, humor, metaphors, or contractions). For more information, see Tone, voice and terms to avoid.
- Write in the active voice and present tense, using positive phrasing. For
Clear the check box, instead of
Ensure that the check box is not selected. For more information, see Creating clear and consistent content.
Clear, consistent technical documentation must follow certain grammar guidelines, many of which add clarity for both native and non-native English speakers. For more information about grammar in technical writing, see Grammar guidelines.
- Write in the present tense as much as possible to avoid confusion for non-native
English speakers and translators, for example:
- Incorrect: After you have installed... when you are installing…
- Correct: After you install... When you install...
It isconstructions. For more information, see Grammar guidelines.
- Avoid possibility: could, should, and would. For example:
- Incorrect: The start date should be in the format mm/dd/yyyy.
- Correct: The start date must be in the format mm/dd/yyyy.
- Whenever possible, prefer constructions that use
thatinstead of a gerund (-ing), for example:
- The system saves the .xml file summarizing the page data to a local server.
- Prefer: The system saves the .xml file that summarizes the page data to a local server.
- The PDC 0007 notifications alerting users to network errors are now less verbose.
- Prefer: The PDC 0007 notifications that alert users to network errors are now less verbose.
PunctuationPunctuation marks are used and interpreted differently in different languages, so it is important not to use punctuation as props to, or replacements for, actual words. For more information, see the Punctuation guidelines.
Do not use dashes parenthetically, for example:
It is at this point – the starting point – that designers and writers meet.
Do not use a slash to mean
either/or. Rewrite the sentence to indicate the exact meaning, for example:
- Incorrect: You can either choose the green/blue one, or both.
- Correct: You can choose the green one, the blue one, or both.
Do not form plurals by adding (s). Either use the proper plural form, or write one or more, for example:
- Incorrect: enter the necessary value(s)
- Correct: enter the necessary values
- Correct: enter the necessary value or values
Do not use an ampersand (&) in a regular sentence to mean
and. If it is part of a proper name, however, do not replace it with the word
Although Pega is a US company, its products have a
global audience. Therefore, we do not necessarily want to use US-specific
terminology, even though we do use US spelling. Instead, use more universal
terminology, especially when you create examples. Some common terms to avoid
US-specific Universal federal governmental foreign non-US Social Security number ID number ZIP Code postal code
British versus American English
In striving to avoid specifically US terminology, we must also be careful not to use
words that are specifically British, such as unique variations of common words. For
while instead of
whilst, as in
I like to do my
knitting whilst I’m watching the telly. Another example: although
apartment is particularly American in origin, it is still more
universally understood than the British
Do not use a keyword as a verb, and do not add a verb ending to a keyword.
- The use of keywords as verbs can cause problems for translators, for example:
- Incorrect: True the Boolean parameter to force users to use the calendar icon.
- Correct: To force users to use the calendar icon, set the Boolean parameter to True.
Choose words that are unambiguous and not easily misinterpreted.
sinceonly to refer to time, not as a synonym for
because. Do not use
- Incorrect: A database administrator can help plan database tables and class groups, as these decisions can influence database performance.
- Correct: A database administrator can help plan database tables and class groups because these decisions can influence database performance.
Ambiguity (from the Greek word
two), is sometimes
introduced when we overlook subtle differences between similar words, for example,
whether. Although in informal speech they can be used
interchangeably, in technical writing the distinction must be noted:
- Use if when one thing is conditional upon another, for example:
- If the database does not load, the connection values are incorrect.
- Use whether to indicate uncertainty about an outcome, for example:
- Incorrect: By verifying an access control policy, you can see if a user has the required access to a case.
- Correct: By verifying an access control policy, you can see whether a user has the required access to a case.
In general, avoid using Latin abbreviations (e.g., i.e., etc.), as
well as the various other small parts of Latin that are common in everyday English,
via instead of
per instead of
vs. instead of
per is acceptable when it is part of a well-established phrase, such as
frames per second, or
cost per mile, etc).
- Not all languages incorporate the same parts of Latin that English does, and
abbreviations and short forms generally do not lend themselves to clear
communication or easy translation, for example:
- Incorrect: Attackers can obtain confidential data via Cross Site Scripting attacks.
- Correct: Attackers can obtain confidential data by using Cross Site Scripting attacks.
- Incorrect: EAR vs. WAR deployment.
- Correct: EAR versus WAR deployment.
May is used in everyday English to express possibility,
permission, hopes, and wishes. In some languages,
may is more interchangeable
can (which expresses definiteness), than it is in English. In technical
documentation, we always want to express ourselves in a definite and absolute way,
can should be preferred over
Apart from making life easier for translators and non-native English speakers, clear, unambiguous sentence structure helps everyone who reads our text, and is a staple of good writing in all of its forms and styles. The following table shows how even the smallest change to a sentence can make a significant difference to both its readability and the clarity of its meaning:
|… the Modules project folder containing the project.||… the Modules project folder that contains the project.|
|If you want to use SSL to implement secure communication between servers, obtain certificates signed by a supported certifying authority.||If you want to use SSL to implement secure communication between servers, obtain certificates that are signed by a supported certifying authority.|
|Your application may need custom classes derived from these base classes:||You can use custom classes that are derived from these base classes in your application if necessary:|
|Your system must pass the user credentials (gathered by the web application) available in the requests to the Gateway and the Gateway can then pass those credentials to the system:||User credentials are gathered by the web application. Your system must pass the user credentials, that are available in the requests, to the Gateway. The Gateway can then pass those credentials to the system.|
Graphics and images
When you create screenshots or choose images and clipart for use in our work, there are certain considerations that you must account for in terms of the global audience:
- Avoid using flags in images. The use of a flag might be falsely interpreted as an expression of approval or sponsorship of that country, or as an affiliation with that country.
- Avoid using images that are specific to a culture or geography. For example, a US-style mailbox might not be recognized in other countries.
Words to avoid
Please and thank you
Technical information requires an authoritative tone. Terms of politeness convey the wrong tone and are not always interpreted the same way in all cultures.
- Incorrect: Please refer to Pega Community.
- Correct: See Pega Community.
If it is necessary to inform readers that they have completed a tutorial or a complex
procedure, say so directly. For example,
You have now completed the tutorial.
Congratulations! or other terms of praise can sound patronizing, and
also create problems for translators. One actual, real-world example is
now big success!
Use verbs as verbs, and nouns as nouns
Many examples of bad technical writing can be found that use verbs in place of nouns,
or nouns in places of verbs. When a noun is used as a verb, it is known as
verbing. For example,
The interviewer peppered the candidate
with questions about his experience, or
The police quizzed the
suspect for hours. Although this is acceptable usage in everyday English, in
technical writing it should be avoided.
- Nouns used as verbs:
- Incorrect: By leveraging the synergy between chatbots and customers...
- Correct: By using the synergy between chatbots and customers...
- Incorrect: Users can author their own content in a low-code environment.
- Correct:Users can create their own content in a low-code environment.
- Verbs used as nouns:
- Incorrect: Click to view the full announce trailer!
- Correct: Click to view the full announcement trailer!
- Incorrect: When you finish the install process...
- Correct: When you finish the installation process...
Take care to avoid typos or mistakes when writing words that can have wrong or
slightly different meanings if they are rendered as compound nouns. In our work, two
particularly common compounds are
backup, for example:
- setup, set up
I set up my new laptop the day it arrived...
...but the setup process went horribly wrong.
- backup, back up
- I had put off doing a data backup for too long...
- ...so I decided to back up my data right away.
Avoid long noun strings
An important part of good technical writing is not chaining together lots of nouns. When three or more nouns are written together, it can be difficult for users to parse their meaning. Technically, the preceding nouns act as adjectives, and readers can think they have ‘found’ the key noun, but have not.
- To avoid possible confusion, consider reordering words, or using prepositions to
clarify the relationship between words, for example:
- Incorrect: Set default printer configuration parameters for new users.
- Correct: For new users, set the parameters for the default printer configuration.
Compare the following two constructions:
In the header of App Studio, and
In the App Studio header. The second phrasing is more concise, but it can also be understood that the header is actually called the
App Studio header. By opening up the construction with the article and preposition, we make it clear that we are talking about
the headerthat is
in App Studio.
Use of the conjunction
that, while technically optional in some sentences, is
never wrong and makes the sentence easier to translate and clearer for users whose
primary language is not English. Some phrases, such as
ensure that… can be
more easily parsed and sound better when
that is included.
- It is easy when reading in your head to skip over the connections between
clauses. On a read-through of your work, check whether you have missed out any
conjunctions, for example:
- Without: Instances of classes derived from the Assign- base class and the Work- base class…
- With: Instances of classes that are derived from the Assign- base class and the Work- base class...
- Without: Ensure your operating system is compatible...
- With: Ensure that your operating system is compatible...
When writing for a global
audience, avoid usage that is culture-specific and possibly confusing. One
problematic area is naming people, for use in examples. To avoid this, use
name instead of
first name or
Christian name, and use
surname instead of
last name. Particularly in the West, a surname
is sometimes called a last name because people write their surnames last, after
their given (or first) names. In other parts of the world, particularly in Asia, the
practice is often the reverse: people's names are shown with their surnames before
their given names.
Examples of sub-optimal writing
Many of the components of good writing also constitute the components of good technical writing, and good technical writing is clear and easily understood by readers of all skill levels. The following table illustrates how the difference between good writing and poor writing can be as small as missing, misplaced, or unnecessary words:
Poor writing Good writing To create another administrator, click
New on the File menu. To create another administrator account, click
New on the File menu. Generally, you are in full-screen mode most of the
time. Generally, you use full-screen mode most of the time. Depending on where you are in the SQL builder… Depending on the section of SQL builder… If you are in the CUSTSERVICE container properties… From the CUSTSERVICE container properties… If you have a sequential file with six fixed width columns,
and you are in the last two columns… If you have a sequential file that contains six fixed-width
columns, you can adjust the width of the last two columns…
Resources for writers
- The Global English Style Guide – John Kohl
- Microsoft Writing Style Guide (Topic: “Global Communications”)
Previous topic Guidelines for topic and article file names, titles, and locations Next topic Good content practices