Writing Style and Tone

Last updated
Save as PDF

Key External Style Guides

Refer to the:

Microsoft Writing Style Guide for technological and user interface terminology.
Chicago Manual of Style for all other aspects including proper usage, punctuation, grammar, citation, etc.
Salesforce Style Guide for Documentation and User Interface Text for a product-specific style guide for TargetX content.

Grammar

Most grammar best practices are outlined in the external style guide(s). Consult the Chicago Manual of Style.

Punctuation

Most punctuation best practices are outlined in the external style guide(s). Consult the Chicago Manual of Style. Additional guidelines are described below:

Use the Oxford (Serial) Comma in all text, including headers.
Use exclamation points sparingly. Exclamation points can be used in welcome messages, closing messages, or for very critical reminders, but should otherwise be avoided.

Apostrophe Use

Most plural and possessive form best practices are outlined in the external style guide(s). Consult the Chicago Manual of Style. Additional guidelines are described below:

The plural form of CAS is CASs.
The plural form of GPA is GPAs.

Capitalization

Most capitalization best practices are outlined in the external style guide(s). Consult the Chicago Manual of Style. Note that you should never capitalize words for emphasis (e.g., don’t use IMPORTANT, DON’T, MUST, etc.). Additional guidelines are described below:

What Else Should Be Capitalized?

Product names (e.g., CAS Configuration Portal).
User interface element names (e.g., “the Save button”).
- Caveat: don’t “apologize” for inconsistencies in the UI. For example, if a Save button is lowercase in the UI, write it in lowercase in the documentation.
Page names (e.g., “the Add Programs page”).
Section names (e.g., “the Colleges Attended section”).
Tab names (e.g., “the Submit Payment tab”).
Object names (e.g., "the Contact object").
Field names (e.g., "the Custom Filter field").
Panel names (e.g., “the Documents panel”).
Features and functionality (e.g., “List Manager,” “Export Manager,” “Work Groups,” “Attribute,” “In Progress,” “Verified,” "TargetX Builder").
Dashboards (e.g., “Applicant Dashboard”).
Standard report names (e.g., “Official GRE Scores”).
- Caveat: in addition to proper capitalization, use double quotation marks for non-standard, customized reports that are generally created by or for specific schools (e.g., “Boston University In-State Applicants”).
AM and PM (not A.M., a.m., or am).

What Else Should Not Be Capitalized?

Words after a colon (i.e., in a bulleted list).
Environments (i.e., production, prelaunch).
- Caveat: environments are capitalized if referencing the page title of the environment-specific guide.
Outputs from features (i.e., list from List Manager, export from Export Manager).

Style and Tone

Keep the following recommendations in mind when writing content.

Tone should be friendly, but respectful.
Language should be simple, clear, and active.
Avoid overly technical or legalistic language except where necessary and appropriate.
Avoid repetition.
Use active voice (e.g., “We fixed the bug” instead of “We have fixed the bug.”).
Avoid slang words and trend abbreviations.
Use second-person voice when possible (e.g., “You must select a program” instead of “The user must select a program” or “A program must be selected”).
Use contractions to keep a friendly tone when possible (e.g., “You can’t add anything else at this time” instead of “You cannot add anything else at this time”).
Use “can” instead of “may” (e.g., “You can change this if needed” instead of “You may change this if needed”).
Use “review” instead of “view" (e.g., “Review the section below” instead of “View the section below”).
Use the gerund in documentation names (e.g., "Selecting a Program"). In CXone Expert, use the gerund in category and guide names; article names and headers can be styled based on the content.

Numbers

Numbers 0-9 should be written out (e.g., zero, one, two, etc.). Numbers greater than or equal to 10 should be written as numerals (e.g., 10, 11, 99, 1,345).

Dates, Times, and Time Zones

Write out months and days instead of abbreviating (e.g., "September 3" instead of "9/3"). This is for clarity, as date abbreviations vary between countries (e.g., month/day versus day/month). If you must use a date abbreviation, then add the date format to the document so it is clear to the reader.

Write times as concisely as possible (e.g., use "1 PM" rather than "1:00 PM"). Always include a space between the time and AM/PM (e.g., 4 AM).

When writing time zones, do not use standard or daylight saving abbreviations (e.g., use "ET" rather than "EST" or "EDT"). This is for conciseness and to avoid confusion for places that do not observe daylight saving time.

If most of the attendees for an event or webinar are located within a certain time zone, then list that time zone first, then Eastern time. For example, if an event is hosted in Central time zone, then you can list times as "8 AM CT/9 AM ET." Or, if a webinar is geared toward California users, then you can list times as "10 AM PT/1 PM ET." If the attendees for an event or webinar are from any time zone, then only list Eastern time.