Things to avoid

Avoid the following items:

• "If you want to …" (and variations) — When providing conditional or optional instructions, do not use "if you want to..." as part of the explanation. Instead, omit "If you want" and begin with "To..."

• "..that" — Avoid. Read the sentence with and without "that". If it make sense both ways, remove "that".

Key terms

active/inactive; not enabled/disabled

When a feature or property is on/off.

activate; not enable

administrator

A person that can change the configuration of Medallia software. Administrators are also users.

allow (permission)

Use allow to indicate permission to do something, not the ability to do that thing. For example, Medallia allows us to take as much PTO as we feel we need. See also enable.

allow-list (noun)

A list of acceptable or permissible items, such as IP addresses allowed to connect to a system.

ampersand (&); use the word and instead

Don't use & (ampersand) as a conjunction. Use the word and instead.

application or app

Software program targeted at users, and which serves specific purpose to the customers.

appears or shows; don't say displays; see open/close

Beta (initial cap)

An early-access period in which limited clients may try out, test, and provide feedback about functionality prior to the feature being made generally available.

blacklist (do not use) say deny-list or exclude-list

builder (lowercase, avoid, say editor)

When referring to a named product entity. Use initial cap like Report editor.

check box (two words)

Classic (for Setup); use Medallia Setup

Don't use Classic or Classic Setup when referring to the old configuration screens in in Medallia Experience Cloud. See Setup below.

click; not click on

When the environment is a desktop with a mouse, use click for most targets, such as buttons, links, list items, and radio buttons.

You may select an option by clicking it.

Hyphenate right-click, left-click, and double-click.

When a click or tap action reveals a collapsed list, you can write click to expand or simply expand.

It's okay to write click in when referring to a region that needs focus (for example: click in the window), but not when referring to a control or a link.

Note: For mobile applications, use tap.

client (avoid)

Alternative term for company which may be used when talking to a 3rd-party audience about the company, such as when talking to a partner-implementer or Professional Services.

close, closes, closed, see open/closed

choose (verb)

Selecting one or more options. Similar to select.

colocate (one word, no hyphen)

combo box (two words)

An input control that combines the features of a dropdown list and a textbox, allowing users to either select an item from a predefined list or enter a custom value.

commas

Use Oxford comma as the final comma in a series of three or more items; use a comma before "and" and "or".

company

An organization that uses/licenses Medallia, Inc. software.

• Companies are also Medallia customers.

• Companies may by clients.

control (UI element)

Any interactive UI element that allows users to perform an action or to input data within an application or website. Buttons, textboxes, and menus are all examples of controls.

CX or customer experience; specific alternative for experience program

Use for CX-specific discussions. Otherwise, use the more general "experience program"

customer (alternative for respondent)

May be used when for a respondent in a customer-experience (CX) or voice-of-the-customer (VOC) situation.

• A person or business that has interacted with a company in some way, and whose feedback is collected.

• Better to say respondent for generic uses.

• Sometimes people or person is a good alternative when talking about someone who has not yet responded (to an invitation)

• Do not use for company or client.

date and time

Unless required by the software

• Include 4-digits for years: 2000 not 00

• Spell out month names: January not 01

• Format:

  • Preferred: 5 March 2003

  • OK: March 5, 2003

  • OK: 5-Mar-2003

  • Do not use: 03-05-2003

• Use 12-hour time, include minutes and the period: 12:00 a.m.

• Say noon (12:00 p.m. or 12:00) or midnight (12:00 a.m. or 00:00) to avoid confusion

• Include timezone when needed for clarification:

  • avoid "daylight savings" or "summer" time designations

  • better to spell out the name, but OK to use abbreviations: Midnight Pacific Standard Time or Midnight PST

  • for a list see https://en.wikipedia.org/wiki/List_of_time_zone_abbreviations

date picker

A date-input UI control that allows users to select a date.

deprecate

To recommend against using an item. Use deprecated for actions for items which will soon be unavailable or unsupported, but have not been made obsolete. See also obsolete.

• Use this global shared note:

  Warning: This feature is deprecated and will be removed in the future. Minimal support is available.

dialog

A rectangular area that covers (obscures) content in a window, contains text and controls, and is not attached to the side of a window. Use dialog for the UI element sometimes called a dialog box. Use dialogue only for verbal interaction between people. See also "panel".

digits

• Use comma in numbers of for or more digits: 5,000

• Use period for decimal separator: 69.99

disabled (do not use); say inactive

displays (do not use); say appears or shows

dropdown list

A type of UI picker that allows users to select one option from a list of options. You can usually say list instead.

dropdown (menu)

One-word. You can often say list instead. A type of expandable menu in which the options are displayed in a list that appears below the menu handle.

editor

The place in the software where you create, define, and edit things like surveys, reports, user accounts. Do not say "builder".

em-dash

In text surround em-dashes with space characters — like this.

• Do not use: em-dashes with no spaces—like this.

employee (alternative for user)

May be used when for a respondent in a employee-experience (EX) voice-of-the-employee (VOE) situation.

• An employee may be a User or admin.

• Sometimes person or people is a good alternative.

enable (avoid); say activate or turn on

In procedures, use the appropriate label and action for the UI element that the user interacts with.

For turning on or activating an option or feature, use enable or turn on consistently:

• Use the same term in introductory text as described in the procedure.

• Use the same term throughout the document unless there's a difference in the UI elements for different procedures.

• Recommended: To activate the account, tick the checkbox.

• OK: To enable the account, click the checkbox.

For making it feasible to do something, say lets you.

• Recommended: The API lets you detect features in images.

• Do not use: The API enables you to detect features in images.

• Do not use: The API allows you to detect features in images.

end-user (do not use)

Vague term. Consider user or respondent instead.

enter (verb)

The act of typing text into a field.

EX or employee experience; specific alternative for experience program

Use for EX-specific discussions. Otherwise, use the more general "experience program"

experience program

Generic and preferred term for CX and EX programs.

favorite (noun)

• Do not use verb form: Favorite the response.

field

A UI element where the user enters a value, often part of a property.

filename; not file name

filename extensions

When referring the a filename extension, include the leading period: "Save as filename.pdf".

When referring to a file type, use all uppercase: "Upload the PDF".

Generative AI or generated using AI; do not say GenAI

hand (do not use for navigation)

Do not say "left hand" or "right hand"; say "left" or "right", include "side" if you absolutely must.

hyperlink (do not use); say link

if; consider using when

"If" is OK to use, but often "when" is better.

• Recommended: When enabled, this feature turns the sky red.

• OK: If enabled, this feature turns the sky red.

image; not picture, photo, or screenshot

• Use abbreviated keyboard key forms: Esc not Escape, Cmd, not Command

• Capitalize the first letter of the name

• Prefer Enter over Return

• To compound keys, use '+' as the joiner : Cmd + Enter

incent, incentive, incentivize

• You incent a person by offering them something (a bribe) to encourage an outcome

• An incentive is the thing you are offering

• You incentivize by turning something (-ize) into an incentive; you cannot incentivize a person

keyboard key names

Latin abbreviations (do not use)

Use proper words instead:

• e.g. — for example

• et al. — and others

• etc. — and the rest

• i.e. — such as or that is to say

• vs or v. — versus

OK and preferred for these:

• a.m.

• p.m.

legacy (avoid, lowercase)

OK to use; avoid if possible; old thing that is still available, but isn't the current new bestest thing available

login (noun or adjective), log in (verb)

For the verb form, sign in is generally better, but if you're documenting a tool that uses the term log in, then use the term that the tool uses.

may (permission), might (possibility)

Medallia expert

Readers sometimes need to know who to contact if they encounter a problem. If there is a specific team that they must contact for help (usually Support), note that. However, in many cases there is no specific team to contact, or the person/team to contact depends on the reader's role. For example, a partner might need to contact Professional Services. A company administrator might need to contact a partner or the Professional Services team, depending on who is managing that company's instance. The general term for this contact is Medallia expert.

• Medallia expert — (first choice term) for general questions
• Medallia representative — (specific) for sales-like issues, such as to get a feature turned on
• Medallia Support — (specific) for assistance, especially to get functionality or support from Ops
• Medallia Operations — do not use; contact Support

navigate (verb)

Navigate to a location (to go to a location)

navigation bar

A type of navigation menu implemented as a menu bar hosting navigation categories.

navigation menu; not hamburger menu

The list of navigation options available from a horizontal bars menu .

Do not confuse with the options menu of three vertical dots .

obsolete

Use obsolete for features that have either been removed or which can no longer be used. See also deprecated.

• Obsolete features should be removed from the product, but sometimes they remain visible but cannot be used. Use obsolete to identify the feature.

• Use this global shared note:

  Restriction: This feature is obsolete and no longer functioning. It is included in this documentation for reference only.

on page; not in/on screen, not in page

open/close; opens, opened, etc

Open and close a screen element, such as a dialog, panel, or window. They may appear.

option

One of multiple choices, often used when referring the options of a property.

options (menu); ok to say more options; not kebob menu

The list of options available from a three-vertical dots menu .

Do not confuse with the navigation menu from horizontal bars .

page (web or desktop); not screen; on page not in page

• A page in a survey.

• Preferred term for web page.

Configuration displays in software products, such as the Setup page. Better is to just say the name of the page, but sometimes you need to add "page" for clarity. For example, administrators create sandboxes on the Sandbox Console page. See also screen.

• Apply the <wintitle> element to the names of configuration pages.

pane

A rectangular area of a window's contents, usually on the right-side of an editor. Better to say just the name, but OK to include "pane" for clarity. For example, "In the Details pane, …" Similar to a "panel", but does not cover content.

panel

A rectangular area attached to the side of a window and which obscures (covers) contents in the window. Similar to a "pane".

When using Tabs for navigation, each tab opens a panel of content.

person or people

Alternative to customer or employee (respondent) who has not responded (to an invitation)

personally identifiable information (PII); avoid the abbreviation, but OK to use

Sometimes called personally identifiable data or personally identifying information; use the alternate forms in only in contexts where you are referring to a UI element or document that uses the term.

please (do not use)

• Recommended: Enter your name.

• Do not use: Please enter your name.

popup tip

A small overlay displaying a brief, informative message that appears when a user taps on an "I" or "?" icon in a touch interface. The popup tip is the equivalent of a tooltip for interfaces that do not support hover gestures (usually, touchscreen devices).

progress bar

A special type of progress indicator that displays the advancement of a process toward completion, usually in the form of a horizontal bar that fills up from left to right as the process progresses. The filled-up part of the bar corresponds to the percentage of the task completed.

progress indicator

A UI element that provides visual feedback on the completion status of an ongoing process, such as downloading a file, loading a webpage, or installing software. Progress indicators set user expectations and reduce uncertainty about the time required for the process to complete and about the state of the system. Progress bars and spinners are two types of progress indicators.

property

• A field, checkbox, dropdown menu, or other on-screen data-entry type administrators use to configure Experience Cloud. Apply the <option> DITA element to the names of properties.

• In API documentation, a property is an element in a resource.

re prefix; no space after "re"

Use the hyphen with the prefix re only when re means again AND omitting the hyphen causes confusion with another word.

• He will recover from his cold — Does not mean again.

• She must re-cover the chair — Means again; confusing without hyphen.

• The song is a reissue — Means again; not confusing without hyphen.

• They try to repress the masses — Does not mean again.

• The cleaner must re-press the shirt — Means again; confusing without hyphen.

respondent

(preferred) Generic for person who provides feedback. Specific respondents may be

• customer

• employee

• people or person when talking about those who have not yet responded (to an invitation)

select (verb)

Select a sequence of text by click-dragging it.

Select an option in a menu by clicking it. Similar to choose.

Setup (initial cap S)

The old configuration screens in Medallia Experience Cloud.

screen (mobile); not page; on screen not in screen

Configuration displays in software products, such as the Account screen. Better is to just say the name of the screen, but sometimes you need to add "screen" for clarity. For example, administrators create sandboxes on the Sandbox Console screen. See also page.

• Apply the <wintitle> DITA element to the names of screens.

screen capture (ok); image (better); not screenshot

sign-in (noun or adjective), sign in (verb); not log in or signin

sign-on, sign on

Don't use either form on its own. Use the hyphenated version as part of single sign-on.

snackbar (do not use); say notification or in-app message instead

An iOS notification that appears briefly and then goes away. Android calls these a toast message.

spam (lowercase)

Unwanted (unsolicited) communications, not to be confused with the product named Spam.

submenu (one word)

subtab

A child navigation object in Medallia Web reporting that contains a report. It is one word, without a hyphen.

survey taker (OK to use)

Specific case and generic term for respondent.

system (avoid, but OK to use)

Replace Medallia system by the product name, for example Medallia Experience Cloud or Experience Cloud.

tab (UI element)

A list item that, when selected, displays a single panel of content. Tabs have labels that describe the content of the panel.

tap

For mobile applications, use for on-screen and soft (capacitive) buttons. Use instead of click when the environment is definitely a touch device. For mechanical buttons, use press.

Use instead of touch. However, touch & hold (not touch and hold) is OK to use.

textbox (one word; OK to say text field or input field)

An input control that allows users to type text within a defined rectangular area. They can be configured to accept a single line of text or multiple lines.

tick (verb); turn on/off (better)

To select a checkbox. Better to say turn on or turn off.

• Recommended: Turn on Confirmation.

• OK: Tick Confirmation.

• Avoid: Tick the Confirmation checkbox.

tile

A rectangular area in the contents of a window that is a UI control (link or button).

time period (noun), time-period (adjective)

Only use one word (timeperiod) if it appears that way in a UI, and then only to refer to the UI element.

time zone (noun), time-zone (adjective)

Only use one word (timezone) if it appears that way in a UI, and then only to refer to the UI element.

toast message (do not use); say notification or in-app message instead

A toast message (primarily Android term) is a notification that appears briefly and then goes away. iOS sometimes calls these a snackbar.

tooltip (one word)

A small overlay displaying a brief, informative message that appears when a user interacts with an element in a graphical user interface. See also popup tip.

use, utilize

• You use something (to accomplish a task)

• You utilize something when converting it into something (-ize) to use for its intended purpose

  • Ambiguous: Teachers do not know how to use computers in the classroom (double meaning: they do not know how to use them?)

  • Clear: Teachers do not know how to utilize computers in the classroom (the know how to use them to teach students)

  • Confusing: Teachers utilize the computer program to empower themselves

user

A person that can sign in to Medallia application, usually to view reports. Some users are also administrators.

• OK: A user of a (Medallia) SDK-enabled application

Twitter (preferred); alternative "X, formerly known as Twitter"

Alternative is per the AP Style Guide as of September 2023.

user elements

Focus on the feature and its functionality, not the UI element. When necessary for clarity, add the name of the UI element.

• Recommended: Go to File > Tools (note the '>' separator for nesting elements).

• Recommended: In the File menu, click Tools.

webhook (one word)

A HTTP request that is triggered by an event, which includes a payload of data, and which may receive and process a response.

website (lowercase w); not web site

One word, not capitalized unless used as a proper noun, beginning a sentence, or to meet other grammatical requirements.

whitelist (do not use); say allow-list

will (passive)

Use active voice instead: say what the thing does, not what it will do.

window

rectangular area of the screen and is a large interface area that contains text, buttons, fields, a close icon, tiles, and more. A window may have panes, and may include panels and dialogs.

workaround (n); work around (v)

Noun is one word, not hyphenated.

you

You is acceptable, but don't use it gratuitously. Say, "Do this", not "You can do this."