Tone, voice, and terms to avoid
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:
| Avoid | Adopt |
|---|---|
| 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 user can...or a manager can... | Use the second person (you) to address users. In instructions, use
the imperative (do this).
|
| Quoting a speaker or Pega entity who is identified:
|
Terms of politeness, such as please, kindly, and thank youconvey the wrong tone. |
|
|
|
| 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. |
Previous topic Don't document the obvious Next topic Creating clear and consistent content