Skip to main content


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

Grammar guidelines

Updated on January 21, 2021

To create clear, consistent documentation that is understandable by all users, ensure that you adhere to the following grammar guidelines:

Placement of the word only

There are many possible ways of writing a sentence containing the word only, and each sentence has an entirely different meaning. It is important to remember to place the word only directly before whatever you want it to modify.

Consider how the meaning changes in the following sentences, based on where only is placed within them:

  • Only an administrator can open the XML files in the dashboard.
    • Administrators are the only users who can open the XML files listed in the dashboard.
  • An administrator can only open XML files in the dashboard.
    • The only thing that Administrators can do in the dashboard is open the XML files listed there.
  • An administrator can open only the XML files in the dashboard.
    • The only type of files that Administrators can open in the dashboard is XML.
  • An administrator can open the XML files only in the dashboard.
    • The dashboard is the only place in which Administrators can open the XML files listed there.

    For more information, including a detailed table of examples, see Correct placement of the word “only”.

Use of the word that

Although the conjunction that can be dropped from a sentence without necessarily affecting the meaning, including that often makes a sentence clearer and easier to read.

Consider the following examples:

  • Without: Verify different users can access the object store content.
  • With: Verify that different users can access the object store content.
  • Without: Ensure your operating system is compatible...
  • With: Ensure that your operating system is compatible...
Users might have to reread the first sentence to grasp the meaning. The second sentence is clearer. Some phrases, such as ensure that… can be more easily parsed and sound better when that is included.

that versus which

Although many people use that and which interchangeably, their usage does have rules. Consider the following examples:
  • The lawnmower that is in the garage needs to be repaired. (Restrictive clause)

    In this example, that is in the garage is essential to the meaning of this sentence. There might be more than one lawnmower, but only the lawnmower in the garage (not any other lawnmowers) needs to be repaired.

  • The lawnmower, which is in the garage, needs to be repaired. (Nonrestrictive clause)

    In this example, which is in the garage is set off with commas because it is not essential to the meaning of the sentence. In this case, only one lawnmower needs to be repaired, and, by the way, it is in the garage.

Another way to remember the difference is that which requires the use of commas, while that does not.

that versus gerunds

Another way in which that aids clarity, improves readability and keeps the imperative mood is by using it, whenever possible, as a replacement for gerunds (verb + -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.
  • Rules referencing data pages by using auto-population properties are quick to obtain access to data.
  • Prefer: Rules that reference data pages by using auto-population properties are quick to obtain access to data.

Transitive verbs

Transitive verbs must have a direct object to indicate the recipient of the action. Do not use a transitive verb without a direct object.

In technical writing, the transitive verbs complete, display, install, and print are often used erroneously without objects. (Note, however, that in this situation the use of the passive voice is correct).

The following examples show incorrect and correct use of the transitive verbs that commonly appear in our work:
  • display
    • Incorrect:This name displays on menus and forms.
    • Incorrect:The screen displays information.
    • Correct:This name is displayed on menus and forms.

    • Correct:A dialog box is displayed.

  • print
    • Incorrect:The document prints.
    • Incorrect:The printer cannot print your document.
    • Correct:The document is printed.
    • Correct:The default printer prints the document.
  • Run
    • Incorrect:After you click Run, the update installs.
    • Correct:After you click Run, the update is installed.
  • Complete
    • Incorrect:When the processing for a flow action completes...
    • Correct: When the processing for a flow action has completed...
    • Correct:To complete the setup, restart your computer.

Split infinitives

A spit infinitive occurs when we place another word, usually an adverb, in the middle of a two-word verb form (for example, to go, to do, to be, etc.). In the sentence To boldly go where no one has gone before, the adverb boldly splits the infinitive verb to go. Despite the popular (and mistaken) perception that split infinitives are to be avoided, they are an acceptable form of phrasing both in everyday English and in our work at Pega.

Note too, that splitting an infinitive with the word not is also acceptable. For example, To configure the section to not display on mobile devices...

False subjects

When this is the subject of a sentence, its antecedent should be the most recent noun. If the intended antecedent is the preceding paragraph or some other, earlier object, then a noun should be inserted. For example, This discussion implies, or This inequality implies, instead of just This implies. One way to understand this issue is to view this only as an adjective, not as a pronoun.

False subjects can be described as any use of vague wording, typically It is or There is/are, instead of a specific subject, for example, The launcher requires a dedicated server. It can be accessed through Dev Studio. (Passive voice is also often seen with false subjects). Does it refer to the launcher, or the server? This passage should be rewritten to specify which one we mean.

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.

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 making use of 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...

following + nouns

Always include a noun after writing the following. Inclusion of a noun adds clarity, prevents ambiguity, and facilitates translation. For example:

  • The following best practices will help you correctly reuse Pega rules in your application:
  • … in the following table:

For more information and examples, see following in the Word List.

  • Punctuation guidelines

    Ensure that you use punctuation correctly to create clear and unambiguous documentation.

  • User interface element reference

    When referring to specific user interface elements, remember to follow the established guidelines so that your content is correct, consistent with our writing standards, and easy to follow.

  • Correct placement of the word “only”

    In our writing, we must be conscious of where we place the word only in a sentence. There are many possible ways of writing a sentence containing the word only, and each sentence has an entirely different meaning. It is important to remember to place the word only directly before whatever you want it to modify. The following table provides guidance about the correct placement of "only" to ensure that your sentences always have the correct meaning.

Tags

Other

Have a question? Get answers now.

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

Visit the Support Center

Did you find this content helpful?

Yes
No

Want to help us improve this content?
Suggest an edit

We'd prefer it if you saw us at our best.

Pega.com is not optimized for Internet Explorer. For the optimal experience, please use:

Close Deprecation Notice
Contact us