Skip to main content

         This documentation site is for previous versions. Visit our new documentation site for current releases.      

Content for a global audience

Updated on January 21, 2021

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.

Basic guidelines

Some of the basic guidelines for good technical writing coincide with the requirements for writing for a global audience:


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...
  • 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 that instead 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.


Punctuation 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.
  • Dashes

    Do not use dashes parenthetically, for example: It is at this point – the starting point – that designers and writers meet.

  • Slashes

    Do not use a slash to mean and/or, or 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.
  • (s)

    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 and.


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 include:

Social Security numberID number
ZIP Codepostal 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 example, use 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 flat.


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.

  • Use since only to refer to time, not as a synonym for because. Do not use as to mean because or while.
    • 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 ambi, meaning two), is sometimes introduced when we overlook subtle differences between similar words, for example, if and 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, such as via instead of through or by, per instead of by or every, and vs. instead of versus. (However, 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, Can

May is used in everyday English to express possibility, permission, hopes, and wishes. In some languages, may is more interchangeable with can (which expresses definiteness), than it is in English. In technical documentation, we always want to express ourselves in a definite and absolute way, so can should be preferred over may.

Sentence structure

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. Using Congratulations! or other terms of praise can sound patronizing, and also create problems for translators. One actual, real-world example is OK, you 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 setup, and 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...
    • 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 header that is in App Studio.

Include that

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...

People's names

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 given 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.

When creating names to use in examples, you can add some global flavor by using diverse names (fictitious, of course) such as Andrea McCartney, Carlos Jiminez, Thinh Nguyen, Maria Bartelli. Many websites list popular given names and surnames, for both men and women.

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 writingGood 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”)

Have a question? Get answers now.

Visit the Support Center to ask questions, engage in discussions, share ideas, and help others.

Did you find this content helpful?

Want to help us improve this content?

We'd prefer it if you saw us at our best. is not optimized for Internet Explorer. For the optimal experience, please use:

Close Deprecation Notice
Contact us