Basic guidelines

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 example, Clear the check box, instead of Ensure that the check box is not selected. For more information, see Creating clear and consistent content.

Grammar

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 There is and It is constructions. 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 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

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

Terminology

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:

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.

Keywords

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.

Ambiguity

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

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.

Congratulations

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

Compounds

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

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:

Resources for writers

• The Global English Style Guide – John Kohl
• Microsoft Writing Style Guide (Topic: “Global Communications”)