Skip to main content

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

Tone, voice, and terms to avoid

Updated on January 21, 2021

In general, informal language and tone are acceptable; however, do not use contractions. We do ask that all team members strive for clear, consistent, and accurate information.

Best practices for language and word choice are as follows:

Filler words like: in fact, itself, quite, very, mostly, definitely, actual, existing, and particular Write crisply. Keep sentences and paragraphs short and to the point
The passive voice Passive voice example:
  • The passive voice should be avoided.
 Active voice examples:
  • Write in the active voice.
  • Select a context for the record by examining the application layer and available rulesets.
  • Future tense conditionals: you should, will probably
  • Vague instructions relying on assumptions
  • Tribal knowledge: once resolved, propagate the handle
  • Write in the present tense
  • Use imperative words
  • Set the proper context when discussing complex concepts
  • Consider Pega Platform users whose first language is not English
the user can... or a manager can... Use the second person (you) to address users. In instructions, use the imperative (do this).
  • On this screen, you can do this
  • On this screen, do this
  • I, we, and our
  • Using we to mean the reader and the writer
Quoting a speaker or Pega entity who is identified:
  • Alan Trefler said, Our product is better than chess!
  • A reader asks, How do we...?
  • Global Client Support clarified the issue: When we said you should do this, we actually meant do that.
Terms of politeness, such as please, kindly, and thank you convey the wrong tone.
  • See Pega Community.
  • You have now completed the tutorial.
  • Engineering jargon like DB, RD, and RARO
  • Generic terms like UI when you mean the portal,the window, or the public API
  • Spell out words such as database instead of using DB
  • Use the specific Pega Platform term, function, or rule
  • Use accepted, well-known acronyms
Latin terms or abbreviations, because many of our readers have no idea what they mean: i.e., e.g., a priori, pro forma If the term is the name or function of a Pega Platform feature, it is okay to use. For example, Ad hoc is a valid Pega Platform term that is used in Reporting and Case Management.
Local jargon, flowery language, and complicated sentence structures Consider readers whose first language is not English.

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