When writing the content of our Study Guides and Practice Exams, we follow guidelines to make our writing style consistent, professional, and user-friendly. We always keep in mind our users by using conversational, concise, clear, and empathetic language.

Conversational Tone

• • Write in such a way that you're having a conversation with our users, instead of the formal writing in textbooks.

  • Address our users using "you" and "we". 

  • Use plain English, unless technical jargon is really necessary. Still, make sure to explain the technical aspect so it will still be understandable.

Be Concise, Clear, and Specific 

• • Keep it short and simple (K.I.S.S.).

  • Avoid complex verb structures and long sentences.

  • Prioritize important points by putting them first.

Writing Style Guidelines

Abbreviations

• • Spell out an acronym or abbreviation the first time it appears and follow with its shortened form in parentheses. Use the acronym or abbreviation in the succeeding statements. Ex. A local area network (LAN)

  • Remove space between a number and unit symbol. Ex. 100%

  • Avoid using e.g. but instead, use for example.

12-Hour Clock Format

• • In writing time, use AM or PM following a space (ex. 12:30 PM). Don't use a.m., p.m., am, pm, A.M., or P.M. 

Modal Verbs

• • Avoid could, may, might, and should because they make the user guess as to what to do.

  • Use can when referring to the ability to do something.

  • Instead of might, use an imperative. Ex. instead of "You might consider this app, rewrite as "Consider this app".

  • Instead of should, use must for something that needs to be done or rephrase as "Salesforce recommends..."

Code Samples

• • Avoid using the type of code to introduce a large amounts of code. Ex. Don't state a code sample in Java as this Java or the following Java.

  • If necessary, use the following terms in reference to the kind of given sample:

    1. Apex script

    2. Apex class

    3. Apex trigger

    4. Visualforce markup

  • In headings, specify the language. Ex. Java Sample or C# Sample

  • Use three spaces to indent the code samples if possible. In some instances, you can use:

• • • two spaces if space is limited

    • four spaces in accordance to Sun, Java, and IDE conventions.

• • Always be consistent with the spaces within a sample and across the lesson.

Compound Words

• • Compound words come in one word, two words, or hyphenated words. Consult with a dictionary to verify the form of the compound word.

  • As an adjective, the compound word is usually hyphenated to modify the noun. Ex. high-performing apps

Datasheet

• • Use datasheet as one word and refers to a list of features about a feature, cloud, or other service set.

Contractions

• • You may use contractions, but not in a contraction from:

    1. a noun and a verb. Ex. Salesforce's launching a new software.

    2. a noun and a verb. Ex. It'll or would've

Italics

• • Use italics for references to the titles of manuals, books, magazines, disks, videotapes, files, audiotapes, catalogs, bulletins, and promotional literature.

  • Avoid using italics in on-screen text because it is difficult to read that text.

Point of View

• • Use of we is acceptable, but never I.

  • Avoid using he or she.

Product Features

• • Begin with active verbs to highlight the purpose and what can be one with the product feature.

Versions and Editions

Product Versions

• • Use earlier instead of lower or below when pertaining to product version numbers. Ex. Windows 2000 or earlier

Editions

• • Omit the in reference to an edition. Ex. Essentials Edition is for small-scale businesses.

  • Bold edition names in tables. Ex. Professional Edition

  • Add Edition and User Permission tables in task topics.

  • Follow the sequence of editions: Contact Manager, Group, Professional, Enterprise, Performance, Unlimited, Developer.

List View Labels

• • Avoid using any format for list view labels.

Lists

• • Bulleted lists are used for items without having any order.

  • Ordered lists present items according to ranks or sequencing.

  • The list can be introduced with the beginning of a sentence followed by a colon.

Ex. The standard objects are:

• • • • Account

      • Contact

      • Opportunity

• • State items in a list or table that is parallel. Either state them in fragments or sentences, but never mix them.

  • Capitalize the initial word of the item whether stated in fragment or sentence form.

  • Omit period for items in fragment form. Use period after each sentence in a list.

Punctuation Marks and Symbols

Apostrophes

• • Use straight apostrophes (') in code samples, while use curved apostrophes in others.

  • Be consistent with the use of apostrophe in release versions and other words or numbers beginning with an apostrophe.

  • Avoid using apostrophes in the plural forms of:

    1. proper nouns, acronyms, and numerals: Ex. FAQs, not FAQ's

    2. single letters, symbols, or mathematical signs

    3. numbers: Type four 5s.

  • Use an apostrophe followed by an s in the possessive case of singular nouns and even proper nouns ending in an s or z sound.

  • Use only an apostrophe in the possessive case of plural nouns.

Brackets and Parentheses

• • Use brackets to separate information within parentheses.

  • Place the period or comma inside the brackets or parentheses enclosing an independent sentence. Otherwise, put the period or comma outside.

Em and En Dashes

Em Dash

• • Em dash is longer than a hyphen (-).

  • Remove space on both sides of the em dash when used.

  • Use em dash when inserting:

    1. parenthetical information to give focus on the information

    2. two or more nouns or noun phrases referring to the same noun

    3.  a list of actions, things, or persons

En Dash

• • En dash is shorter than an em dash.

  • Use en dash for indicating minus symbol or ranges for dates, number, and time. Ex. 1990–2000

Hyphen

• • Use hyphen:

    • in compound words

    • if prefix ends with a vowel and the word starts with a vowel. Ex. pre-existing

    • to connect a number to a measurement that is used as an adjective. Ex. 10-point type

    • in fractions and numbers written as words. Ex. one-half, twenty-one

  • Avoid using hyphen:

    • for the prefixes that usually don't need a hyphen are ante, bi-, bio-, co, counter-, extra-, infra-, inter-, intra-, macro-, mid-, mini-, multi-, non-, over-, post-, pre-, pro-, pseudo-, re-, semi-, sub-, super-, supra-, trans-, ultra-, un-, and under-.

      • Exceptions: 

        • if the prefix is used with a proper noun or numeral. Ex. trans-Atlantic or post-2000

        • the compound is a homonym. Ex. re-create (to create again) and recreate (amuse oneself with an activity)

    • before text in Rich Text Area or Long Text Area

  • When arranging terms alphabetically, begin with spaces and followed by hyphens, then numbers and then letters. Treat a hyphen as a space. Ex.

    • W2L

    • Web Tab

    • Web-to-Lead

    • Web2Lead

End Punctuation

• • Use the user interface's exact label, including any end punctuation like an ellipsis. Ex. Click Add... to browse for files on your local computer.

Folder Names

• • Avoid quotation marks or other formatting for folder names. Use the same folder name as found in the user interface.

Mathematical Terms

• • Avoid adding apostrophe and s to mathematical signs for their plural form.

  • State mathematical signs by spelling out their name and indicate their symbol in parentheses. Ex. Add one space one side of an equal (=) sign.

Capitalization

• • Capitalize proper nouns.

  •  Avoid using all caps to emphasize the word.

  • Avoid beginning a sentence with a code element. Rewrite the sentence so that it does not start with the code element.

Titles and Headings

• • Capitalize: 

    1. nouns, pronouns, verbs, adverbs, and subordinate conjunctions

    2. the first word in subtitles placed after a colon in titles. Ex. Activity Settings: Tasks and Events

    3. the second word in a hyphenated compound. Ex. Third-Party Software

    4. key names. Ex. Alt, Ctrl, Del

  • Use lowercase for:

    1. articles, coordinating conjunctions, and prepositions

    2. the to in an infinitive. Ex. Topics Added to Records

  • Use the case of objects, calls, methods, SOAP headers, and any code element. Ex. the Account object or create()

Acronyms, Editions, File Extensions, and Links

• • Capitalize the individual words if the acronym stands for proper nouns. Ex. Web Services Description Language (WSDL)

  • Capitalize both words in an edition name but not when used as a common noun. Ex. Enterprise Edition

  • Use lowercase for file extensions used in sentences. Refer to Ex. Create a .zip file containing .csv file.

  • Capitalize file extensions if used in headings. Ex. Importing .Zip Files

  • Capitalize link text as used in context. If the link text has an element that is capitalized in the UI, make sure to capitalize it also in the link text.

UI Text

• • Use the same capitalization for the UI label in the user interface.

  • Avoid capitalizing tab. Ex. Accounts tab

  • Avoid capitalizing report except when included in the report name.

Files and File Names

• • Avoid capitalizing file if part of a name, except when part of heading or proper name. Ex. Attach files to records.

  • Use the exact spelling and capitalization found in the program or file itself.

  • Use lowercase for file extensions within a sentence. Ex. Export a .txt file.

  • Use title case for file extensions within a heading. Ex. Renaming .Txt Files

  • File name is written as two separate words.

Job Titles

• • Capitalize job titles only if used as a formal title of a person. Otherwise, use lowercase when stating the job title without a person's name or simply stating the general duties and responsibilities.

Capitalizing Other Words

• • Capitalize and use Customer Support with the company's name. Ex. Salesforce Customer Support

  • Capitalize database as part of a heading or a proper name. Ex. Microsoft Azure SQL Database Connection

  • The following words must not be capitalized when used as part of a name, except in a heading of part of a proper noun: database, field, file, process, program, record, report, screen, segment, subtab, and tab

  • Capitalize J and S in JavaScript, which must be written also as one word.

  • Avoid capitalizing field if part of a name, except when part of heading or proper name. Ex. custom field

  • Capitalize key names and avoid using the bold format. Ex. Alt or Right Arrow 

User Interface Elements

Documentation 

• • Bold the text referred as buttons. Ex. Click Delete.

  • Avoid adding the following UI element types except when necessary: button, checkbox, drop-down button, field, icon, menu, link, radio button, or window. Ex. Click View, not Click View button.

Drop-Down Buttons

• • Use drop-down button when talking about a button that expands, presenting several options.

  • Use the general format Click X and Select Y. Ex. Click Add New and select Field Update.

Drop-Down Lists

• • For a picklist field, follow the guidelines for field names.

  • For a user interface widget, no need to emphasize drop-down list using any special formatting. Ex. Click Edit next to the View drop-down list.

  • Avoid using quotation marks or any special formatting. Ex. User License drop-down list

Word Usage

Administrator/Admin

• • Use Salesforce adminstrator when referencing logging in. It's all right to use the shortened Salesforce admin when repeated a few times.

App

• • Use  app, except when referring to:

    1. Salesforce application or just use Salesforce if the context is given

    2. being included in a license, permission, or product name. Ex. Email application permission

And/Or

• • Avoid using and/or. Just rewrite the sentence to convey a clear meaning. Or can refer to either or both. Ex. In Chatter External, users have no access to Chatter objects or data.

Checkbox

• • Use Checkbox as one word and must be use with select or deselect.

Dialog Box

• • Use Dialog box to refer to a window with buttons and a selection of actions to perform an action. Avoid using dialog, dialog window, or dialog popup.

Drag

• • Use drag as a verb to transfer an item to a place. Ex. Drag a saved segment from Segment Templates. 

Drag-and-Drop

• • Use drag-and-drop as an adjective and not as a verb or noun. Ex. A simple drag-and-drop interface

Email

• • Use email without the hyphen. Its plural form is emails.

Etc.

• • Never use etc. Instead, specify the information.

For Example

• • When the statement includes an example, introduce for example.

  • Avoid using e.g., i.e.,  or example.

Field Names

• • Use on instead of in if field is used in relation to objects. Ex. Create a custom field on a standard object.

  • If the user is instructed to choose or enter a value, tag the valye as <userinput>. If not, use <codeph> for values such as field defaults or acceptable values. Never use quotation marks for these values.

  • Use monospace font for field names. Ex. Account Rating formula field

Filter Criteria

• • Use monospace font for filter criteria. Ex. Current User Profile: ID

Following

• • Avoid following to point out the location of an element. Ex. The following table

  • Refer to the element directly with the use of this or the. Ex. This table

  • Use later or following to state upcoming information, but avoid using below.

Hover

• • Avoid using mouse over to instruct that the mouse pointer must be moved over an icon, field, or button. Instead, use hover over. Ex. Hover over a case number to make case hovers appear.

That Is

• • Use that is instead of i.e.

  • Use a parentheses to enclose that is or namely with the element that it introduces when a comma isn't sufficient to signal a break in continuity.

Imperatives

• • Use imperatives when needed and in task topic titles.

iPad and iPhone

• • Avoid adding -s for the plural form of iPad and iPhone. Instead, use devices. Ex. iPad and iPhone devices

Jargon and Cliches

• • Avoid jargon and cliches, which are overused words and phrases such as user-friendly, innovative, hands-on, ease of use, robust, intuitively, etc. 

  • Simplify technical jargon by making them understandable to our users. Clearly define them when needed.

Press

• • Use press for key names instead of click or hit. Ex. Press Ctrl

Keyboard and Key Names

• • For key combinations, use the plus sign. Avoid adding space before or after the plus sign. Ex. Ctrl+S

Shortcut

• • Use shortcut when referring to a keyboard shortcut. Avoid using command.

Later

• • To state upcoming information, use later or following instead of below. Ex. Later in this guide

Latin Abbreviations

• • Avoid using Latin abbreviations. Rephrase them or use their English equivalent.

    • and others (et. al.), and so on (etc.), for example (e.g.), namely (iz.), that is or in other words (i.e.)

Object and Object Names

• • Avoid object names in text. But when really needed, avoid complex grammar and use the object name as the subject of the sentence. Ex. Accounts are the companies you do business with.

  • Be specific like the name of the record. Ex. Here is the sharing for My Big Opp.

  • Use record or object as a generic term rather than the object's standard name. Ex. This record's sharing setting is private.

iOS

• • iOS is one word with a capitalized O and S.

  • iOS refers to the operating system in Apple's line of mobile devices, which are the iPad and iPhone.

  • Use iOS with specified version, but don't add the word version. Ex. iOS 4.2.1

Internet

• • Capitalize Internet when referring to the Internet, which is a noun.

  • Use lowercase internet when used as an adjective. Ex. internet banking

Measurements

• • Use numerals.

  • Repeat the unit of measure for at least two quantities. Ex. Between 15 cm and 30 cm

  • Abbreviate units of measure if common to the users. Ex. KB, GHz

  • Spell out the unit of measure to avoid confusion such as inches (in). Use the abbreviated form in tables or other condensed format.

  • When a measurement is referred to as an adjective, place a hyphen between the number and the unit of measure. Ex. 10-point type

  • No need to add a period after the units of measure if placed within the text.

Word Distinctions 

And vs Ampersand (&)

• • Always spell out and. Exceptions for using ampersand (&) is when it's included in a company name, logo, proper noun, tor title, or when screen real estate is an issue.

Above vs Below

• • Avoid using above and below to point out the location of an item. When needed, replace above with preceding  or previous. For below, use later or following instead. 

Click vs Select

Click

• • Use click when referring to: 

    1. an action of issuing a command or selecting options in a dialog box. Ex. Click Start.

    2. clicking the left mouse button, while right-click refers to the right mouse button

  • Avoid using Click on or Click at.

Select

• • Use select when referring to:

    1. marking text, cells, and similar items subject to user action. Ex. Select the settings of your choice and then click Save.

    2. placing a check on a check box or choosing an item in a list box

  • Avoid using pick as a synonym to select.

Deprecated vs Desupported

• • Avoid using deprecated to refer to an available feature that is no longer supported. Use not supported instead.

  • Avoid using desupported to refer to an unavailable feature. Describe the feature as no longer available instead.

Disable, Disabled, and Unavailable

• • Use disable when the act will make something unavailable. Ex. Select Disable end user personalization of nav items.

  • Use disabled for a feature that is not enable. Ex. Your account has been disabled.

  • Use unavailable describe a menu item, drop-down list option, or other selection that is not usable. Ex. Price books can be made unavailable to some sales rep.

Display vs View

• • Use display to refer to what a Web browser or the app does. Ex. The record page displays the update layout.

  • Use view to refer to what a user does. Ex. You can view and manage all your users in your org in the user list.

Hard Code, Hard Coding, and Hard-Coded

• • Hard coding means the software development practice of embedding output or configuration data directly into the source code of a program.

  • Hard code and hard coding as two separate words are used as a noun or verb.

  • Hard-coded with a hyphen is an adjective.

Install vs Installation

• • Use install as a verb. The noun is installation.

Login vs Log in

• • Login is a noun, while log in is a verb. Ex. Log in to Gmail. The login page is where you enter your username and password.

----List of @Mention next

Reference

• Salesforce Style Guide for Documentation and User Interface Text