Language and grammar
When you review content, pay special attention to language and grammar.
Punctuation
- Is the serial comma present?
- These data sources include classes, properties, authentication profiles, and connectors.
- Is there a comma between two independent clauses, followed by
and then
in step commands?Click Options, and then click Allow Fast Saves.
The model gathers responses, and the algorithm updates the predictions.
- Is there no
comma splice
?- Incorrect:
The clipboard contains three groups of pages, they serve a different purpose.
- Incorrect:
- Are commas used:
- After introductory phrases?
On the Settings tab, click Email instantiation.
For more information, see <link>.
- After dependent clauses?
If your application supports localization, select a language-specific ruleset for the field value.
- Between adjectives, if their order is interchangeable?
The feature provides immediate, constant access to all customer records.
- Before which, where appropriate?
Attributes are unique security markings whichthat are assigned to objects and operators.
Each attribute has a value associated with it,which means that a user must possess an attribute value to access an object.
- After introductory phrases?
- Is punctuation with parentheses correct?
- You might need to create several properties, all with the same Applies To class (and ruleset version).
- You might need to create several properties, all with the same Applies To class. (The same guideline applies to the ruleset version.)
- Is punctuation with quotation marks correct?
- One Internet dictionary calls an electronic magazine a “hyperzine.”
- One Internet dictionary calls an electronic magazine a “hyperzine,” but webzine is a common synonym.
- What is a “smart device”?
- A reader asks, “How scalable is .NET?”
- Are hyphens used judiciously?
- Many words with prefixes are not hyphenated: autogenerate, multimode, preinstallation, postinstallation, substrategy
- Exception: re-create
- Is the possessive apostrophe avoided?
Tense
- Is the present tense used whenever possible?
- Is the continuous present tense avoided?
- Correct: If you edit...
- Incorrect: If you are editing...
- Is simple past tense used when you need to describe past events?
- Incorrect: If you have selected the check box in the first step…
- Correct: If you selected the check box in the first step…
- The best: If you configure Check box name...
- Are future and conditional tenses (will, should) avoided?
Terms to avoid
- Allows, lets, enables
- Tell users what they can do, not what the software “allows” them to do.
- Latin abbreviations and words: e.g., etc., i.e.
- Abbreviations: admin, db, DBA, sales rep, customer service rep
- Machine
- Use computer or server instead.
- Exception: machine learning
- Quotes, quote marks
- Use quotation marks to refer to these punctuation marks: “ ”.
Common typographical errors
- "Javascript" should be "JavaScript"
- "manger" should be "manager"
- "Pega platform" should be "Pega Platform"
- "RuleSet" should be "ruleset"
- "sever" should be "server"
- "a SQL database" should be "an SQL database"
- When referring to Structured Query Language as SQL, SQL is pronounced “es-cue-el” and takes the indefinite article an. An example is “an SQL database.”
- When referring to the product or the server that is running the product, SQL is pronounced sequel.”
- "the the" should be "the"
- "Unix" should be "UNIX"
Problematic words
- Backup, back up
- Make a backup copy of your Microsoft Windows registry.
- Back up your files to a remote server.
- The system creates a backup of the ruleset in the temporary directory.
- Cleanup, clean up
- Provide the data transform to apply to the clipboard cleanup in the Apply data transform field.
- Clean up the clipboard by providing a data transform.
- Setup, set up
- Internet Explorer setup
- How to set up Internet Explorer
- Install, installation
- Install is the verb; installation is the noun or adjective
- Install the software before you eat a piece of cake.
- After you finish the installation, have a piece of cake.
- Refer to the installation guide for complete instructions.
- Install is the verb; installation is the noun or adjective
- Displays
- Display is a transitive verb. Either something is displayed* (by the
software) or something displays something. *The use of passive voice
is acceptable in this context.
- This category is displayed only for top-level case types. (Not “this category displays….”)
- Select the name of a flow action in the first field that is displayed. (Not “the first field that displays…”)
- If you delete a function without deleting the references, an error message is displayed. (Not “an error message displays”)
- Display is a transitive verb. Either something is displayed* (by the
software) or something displays something. *The use of passive voice
is acceptable in this context.
Redundant phrases
- You can add one or more additional properties…
- You can add one or more properties…
- To create a new rule…
- To create a rule...
- You can group together similar rules…
- You can group similar rules...
- Before you log in, you must first create a password.
- Before you log in, you must create a password.
Previous topic Content elements Next topic Task topics