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:
|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 (|
|Quoting a speaker or Pega entity who is identified:|
| Terms of politeness, such as |
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