Sections

Documentation Usage Dictionary

This usage guide covers common usage concerns about BriteCore documentation, RFIs, RFPs, and proposals. Its purpose is to standardize language, spellings, URLs, and other informational items covered within these types of documents. While this guide addresses recurring issues, it can’t cover every scenario and should be treated as a living document.

A

Address bar

To describe the text box in a web browser displaying the current web page address, use address bar.

Don’t use browser bar, navigation bar, location bar, or window bar.

Admin

Don’t use in any instance. Use administrator instead. This includes the Provider Administrator portal (not Administrative portal or Admin portal).

Administrator

Always use instead of admin.

Admin/Administrative portal

Don’t use in any instance. Always refer to it as the Administrator portal.

Agile

Present agile in lowercase. If agile is part of a name or title, follow the capitalization of the name or title.

Example:
BriteCore follows an agile development methodology.

Among

Among is not interchangeable with between. Use among when the items or elements are not distinct and are referred to as a general group. The elements discussed must include three or more items, groups, or people.

Example:

Correct: The negotiations among the South American nations are going well.

Incorrect: The negotiations between the South American nations are going well.

Use between for separate and distinct (two or more) items.

Examples:

Correct: The negotiations between Brazil, Argentina, and Chile are going well.

Incorrect: The negotiations among Brazil, Argentina, and Chile are going well.

When location is concerned, each word implies different information.

Examples:

Navigating between the Lines, Policies, and Claims modules is easy. (Navigating back and forth between these three specific modules is easy.)

Navigating among BriteCore’s primary modules is easy. (Navigating from any primary module to any other primary module is easy.)

The man walked between the trees. (The man walked between two specific trees or walked on a route flanked by trees.)

The man walked among the trees. (The man walked in a forest or wooded area, but not necessarily on a set path.)

Auto-

In general, don’t hyphenate words beginning with auto-, such as autopay and autodial, unless it’s necessary to avoid confusion. When in doubt, check The American Heritage Dictionary.

Don’t create new words beginning with auto-.

B

Between

Between is not interchangeable with among. See the entry for among for more information.

Bold

Use only as an adjective, not as a noun or verb. Don’t use bolded, boldface, or boldfaced.

Book roll

Spell book roll as two words.

Box

When you need to refer to dialog box elements by name, use box instead of field to refer to any box except a check box or a list box. For a check box, use the complete term, check box. For an element that displays a list, such as a dropdown list, use list instead of box for clarity.

Examples:

  • the Read-Only box
  • the File Name box
  • the Hidden Text check box
  • the Products list

Don’t use box as a synonym for client and server hardware.

Bullets

Inline bullets. To produce an inline bullet, press Option+8 on the Mac keyboard.

Button

When you need to discuss UI elements, use button instead of command button, option button, or action button. If possible, refer to a button by its label only without using the word button. If you need to use the word button for clarity, button is lowercase.

C

Canceled

Spell canceled with one l instead of two.

Capitalization

General guidelines

Use sentence-style capitalization most of the time.

  • Capitalize the first word of a sentence, heading, title, UI label (such as the name of a button or check box), or standalone phrase.
  • Capitalize proper nouns. To learn more about proper nouns, see Nouns and pronouns.
  • Use lowercase for everything else.
  • Always capitalize the first word of a new sentence. Rewrite sentences that start with a word that’s always lowercase.
  • Don’t use all uppercase for emphasis. (It’s okay to use italics sparingly for emphasis.)
  • Don’t use all lowercase as a design choice. Although all uppercase is used occasionally as a design element, don’t use it in text.
  • When words are joined by a slash, capitalize the word after the slash if the word before the slash is capitalized.

Examples:

Country/Region

Turn on the On/Off toggle.

Specific use cases:

BriteCore modules. Capitalize the name of the module, but not the word module.

Correct: Lines module

Incorrect: Lines Module

BriteCore portals. Capitalize the name of the portal, but not the word portal.

Correct: Policyholder portal

Incorrect: Policyholder Portal

CDT

See Central Time.

Central Time

CDT stands for Central Daylight Time, which represents a time zone in the US Midwest during its “spring forward” period to daylight saving time. CDT generally occurs between March and November. CDT is sometimes represented as GMT-05:00 or UTC-5.

CST stands for Central Standard Time, which represents the same time zone during its “fall back” period to regular time. CST generally occurs between November and March. CST is sometimes represented as GMT-06:00 or UTC-6.

Unless you mean the specific periods of the year listed above, use Central Time, US Central Time, or CT instead.

Check box

Spell check box as two words.

Choose

Use choose to instruct users to choose an option, based on their preference or desired outcome.

Clear

Use clear to instruct users to clear the selection from a check box.

Click

Avoid click, which is specific to using a mouse and doesn’t apply to tablets or other mobile devices that use a touch-based interface. Instead, use select.

Close

Use close to instruct users to close the following UI elements:

  • Apps and programs
  • Blades
  • Dialog boxes
  • Files and folders
  • Notifications and alerts
  • Tabs

Commas

Use serial commas (Oxford commas) between all items in a list and before the terminal and, but, or, and other coordinating conjunctions.

Separate independent clauses in a sentence with commas.

Examples:

I took a chance, and I paid the price.

The flight from Sacramento, which everyone thought would be late, arrived half an hour early.

Do not insert commas to offset a dependent phrase.

Correct: The dog that has distemper and bit me still roams free.

Incorrect: The dog, that has distemper and bit me, still roams free.

Refer to the style guide for additional guidance.

Composed of/comprised of

Compose means to make up or form something. Comprise means to include, contain, or consist of something. They aren’t interchangeable.

Examples:

Correct: Seven dashboards compose the module. (Seven dashboards make up/form the module.)

Correct: The module is composed of seven dashboards. (The module is made up/forms seven dashboards.)

Correct: The module comprises seven dashboards. (The module includes/contains/consists of seven dashboards.)

Incorrect: The module is comprised of seven dashboards. (The module is included of/contained of/consisted of seven dashboards.)

Note: Replace comprised of with consists of, made up of, or other similar phrasing. You can also rewrite the sentence to use a form of compose instead.

To remember the difference between the two, just remember:

  • The whole comprises or is composed of the parts.
  • The parts compose the whole.
  • “The whole is comprised of the parts” is logically incorrect.

Continually

Continually means ongoing, but with interruptions or breaks. Continuously means ongoing without interruptions; ceaseless.

Control

In content for a general audience, don’t use control to refer to a UI element such as a text box, check box, or list box. It’s okay to use control to refer to adding a user-defined control in a program.

In other contexts, it’s okay to use control.

CST

See Central Time.

CT

See Central Time.

D

Datadog

Datadog is spelled with a lowercase internal d. See the copyright notice at https://www.datadoghq.com.

Dialog box, dialog, dialogue

When you need to refer to a dialog box, use dialog box—don’t shorten to dialog. Don’t use pop-up window or dialogue box. A dialog box requires the entry or input of text/information/selections; a pop-up window is informational, such as a warning or other notification.

Don’t hyphenate dialog box as a modifier.

Examples:

Google Drive can’t open this document because a dialog box is open. Close the dialog box to continue.

Select the Paragraph dialog box launcher, and then select Tabs.

Exception:

In content for developers, it’s okay to use dialog by itself as a modifier. For example, This article provides information about the dialog form pattern.

Use dialogue (not dialog) to refer to conversation or interaction between people or between a person and a computer; however, use a more familiar, friendlier term such as conversation or chat if you can.

Examples:

It’s a great way to have a conversation with the customer about what cloud technology can do for their business.

Do you want to chat with a customer service agent?

Note: In BriteCore, a dialog box is sometimes referred to as a modal.

Dropdown

Use dropdown as an adjective when you need to describe the type of UI item or how it works.

Note: While drop-down list is technically correct, use dropdown list to match BriteCore’s UI.

Examples:

Correct: In the Company dropdown list, select BriteCore.

Incorrect: Use the dropdown to select a company.

Don’t use dropdown as a noun or verb.

E

e.g.

Don’t use. Use for example, such as, or like, as appropriate.

Elasticsearch

Amazon spells Elasticsearch as one word with an internal lowercase s. See https://aws.amazon.com/elasticsearch-service/what-is-elasticsearch/.

Enter

Use type instead of enter.

F

Field

Don’t use to refer to a text-entry box. Refer to the box by its label. If you must use a descriptor, use box instead of field. See Box for more information.

It’s okay to use field to refer to Word field codes, in a database context, and in other technical contexts.

G

GitHub

GitHub is spelled with an internal capital H. See https://github.com.

Go to

Use go to when instructing a user to complete the following tasks:

  • Opening a menu.
  • Going to a tab or another particular place in the UI.
  • Going to a website or webpage.
  • It’s okay to use On the XXX screen,… if the instruction is brief and continues immediately.

H

Headings

Writing headings

  • Think of headings as an outline
  • Keep headings as short as possible
  • Be as specific as you can
  • Focus on what matters to customers
  • Use parallel sentence structure for all headings at the same level

Formatting headings

  • Use sentence-style capitalization
  • Don’t end headings with a period
  • Break two-line headings carefully
    • Keep adjectives and prepositions with the words they modify
    • Keep hyphenated words and multiple-word proper nouns (such as New York) on the same line
    • Break after punctuation
    • Break naturally, at the end of a complete phrase, if possible
    • Rewrite a headline if you can’t fit it on two lines

Here

Avoid using here within a link. Here creates several problems. First, it doesn’t provide context for the linked material. Second, it creates accessibility problems for people with visual impairments who use screen readers. If they pull up a list of links for navigation and hear repeated instances of here, they can’t navigate effectively. Third, contextual links provide higher SEO value.

Examples:

Correct: Many of our customers are InsurTechs that use BriteCore in a headless use case (view an example case study).

Incorrect: Many of our customers are InsurTechs that use BriteCore in a headless use case (view an example case study here).

Hit

Use press instead of hit or strike.

HTTP and HTTPS

Use lowercase http and https when used in the protocol of a URL. Use uppercase HTTP and HTTPS when used in a phrase or sentence.

I

i.e.

Don’t use. Use that is instead.

Icon

When referring to an icon, use bold formatting for the icon name. In instructions, use the name of the icon and its image, but don’t use the word icon.

Note: Use only to describe a graphic representation of an object that a customer can select and open, such as a drive, folder, document, or app.

In order to

Replace in order to with just the word to.

In regard to

The phrase is always in regard to, not in regards to. Regarding is better.

InsurTech

InsurTech is the preferred spelling, with no e following the r and with an internal capital T.

Intuitive Web Solutions (IWS)

Don’t use. Use BriteCore instead.

Involved party

A person identified as an owner, driver, or passenger on a claim.

J

JavaScript

Spell JavaScript with an internal capital S.

Just

Avoid using just.

K

Key combination

Don’t use. Use keyboard shortcut instead.

Key sequence

Don’t use. Use keyboard shortcut instead.

Keyboard shortcut

Use to describe combinations of keystrokes used to perform a task that usually requires a mouse.

Keypad

Always use numeric keypad instead to avoid possible confusion with keyboard.

Keypress

Don’t use. Use keystroke instead.

Keystroke

Keystroke is one word. Use instead of keypress.

L

Leave

Use leave to instruct users to exit websites and webpages.

Like versus such as

Such as denotes examples of specific, definite things. It implies inclusion. Use such as as you would e.g. to list specific, included examples of something.

Like is used to compare things with similar qualities or attributes. It implies comparison.

Links

Set links to external webpages to open in a new browser tab. In many interfaces, the option is often labeled as target and the specific setting as new window.

Example

Lockbox

Spell lockbox, as in lockbox API, as one word.

M

Menu

Always surround menu names with the words the and menu both in text and procedure.

Correct: In the File menu, select the file you wish to open.
Incorrect: In the menu, choose a file.

Modal

In BriteCore, a dialog box is sometimes referred to as a modal.

Modules

When referring to a module in BriteCore, capitalize the name of the module, but don’t capitalize the word module itself.

Correct: Polices module

Incorrect: Policies Module

Multi-

In general, don’t hyphenate words beginning with multi- unless it’s necessary to avoid confusion or multi- is followed by a proper noun. Check The American Heritage Dictionary if you are unsure. If you don’t find the word there or in the following list, use multiple before the word instead. Don’t invent new words by combining words with multi-.

Examples:

  • multicast
  • multichannel
  • multicolumn
  • multilevel
  • multiline
  • multilingual
  • multimedia
  • multiprocessor
  • multitasking
  • multiuser

N

Named insured

Use named insured to describe a person whose name is listed on the policy.

Navigation

Use navigation to refer to the navigation links across the top of the screen in BriteCore, as shown in the following screen capture. Do not use navigation list or navigation panel.

Nationwide

When using as an adverb or adjective, spell nationwide as one word. See examples in the American Heritage Dictionary.

New

Avoid using new, since things don’t stay new for very long.

Now

Avoid using now.

O

On a daily basis, on a nightly basis

Don’t use. Use daily, every day, nightly, or every night instead.

Only

Be careful to place the adjective only so that it modifies the intended word. In the following sentences about an option exclusive to a specific user role, note the subtle difference in meaning based on the placement of only:

Correct: The delete line option is available to superusers only. (Superusers are the only people who can use the delete line option.)

Incorrect: The delete line option is only available to superusers. (That is, the option isn’t selectable or even visible to superusers; it is only available.)

Incorrect: The delete line option only is available to superusers. (No other option is available to superusers.)

The following simple examples further highlight the importance of the placement of only:

Only John hit Peter in the nose. (No one else hit Peter.)

John hit Peter only in the nose. (John didn’t hit Peter anywhere else.)

John only hit Peter in the nose. (John didn’t do anything else to Peter or his nose except hit.)

John hit only Peter in the nose. (John did not hit anyone else in the nose.)

Open

Use open to instruct users to open the following UI elements:

  • Apps and programs
  • Blades
  • File Explorer
  • Files and folders
  • Shortcut menus
  • Use for websites and webpages only when necessary to match the UI. Otherwise, use go to.
  • Don’t use for commands and menus.

Other party

A person who is not identified as an involved party but is still eligible for coverage under the named insured’s policy.

P

Page

Don’t use. Use screen instead of page.

Pass-through authentication

The phrase pass-through authentication contains a hyphen between pass and through.

Phone numbers

Express US phone numbers in the (417) 555-1212 format for consistency.

Pop-up

Don’t use as a noun. For example, don’t use a pop-up; use a pop-up window instead.

Don’t use pop up or pops up as a verb to describe the appearance of a window. Use open or a similar verb instead.

It’s OK to use pop-up window to refer to windows that pop up in Help. Don’t use pop-up window as a synonym for dialog box. A dialog box requires the entry or input of text/information/selections; a pop-up window is informational, such as a warning or other notification.

Portal

When referring to a portal in BriteCore, capitalize the name of the portal, but don’t capitalize the word portal itself.

Pre-

In general, don’t hyphenate words beginning with pre-, such as preallocate, prepaid, or preempt, unless it’s necessary to avoid confusion, as in pre-engineered, or if pre- is followed by a proper noun, as in pre-C++. When in doubt, refer to The American Heritage Dictionary.

Presently

Use currently to mean “at the present time.” Presently can mean “soon.”

Example

The feature is unavailable currently.

Press

Use press instead of hit or strike.

Preventative/preventive

Use preventive for consistency.

Pull request

GitHub’s practice is to spell pull request in lowercase. The abbreviation PR is acceptable for audiences that will understand its meaning.

Q

Quarters of the year

When referring to quarters of the year, keep the presentation consistent by using the following format: Qx of 20xx.

Correct: Our BriteClaims module is scheduled to be released Q2 of 2019.

Incorrect: Our BriteClaims module is scheduled to be released Q2-19.

R

Re-

In general, don’t hyphenate words beginning with re- unless it’s necessary to avoid confusion or re- is followed by a proper noun.

Right-click

Right-click is hyphenated.

S

Second person

In general, use second person, which means you write as though you’re speaking to the reader. Second person often uses the personal pronoun you, but sometimes the word you is implied. Using second person supports a friendly, human tone and helps avoid passive voice by focusing the discussion on the reader.

Examples

Create your own unique BriteCore experience.

You can set advanced options later if you need them.

Note: Consider omitting you can whenever the sentence works without it.

Select

Use select to instruct users to select a specific item:

  • Selecting an option, such as a button.
  • Selecting a check box.
  • Selecting a value from a list box.
  • Selecting link text to go to a link.
  • Selecting an item on a menu or shortcut menu.
  • Selecting an item from a gallery.

Separate

Avoid spelling separate as seperate.

Screen

Use screen instead of page.

Sidebar

Sidebar is one word. Use sidebar instead of menu, left menu, navigation list, or navigation panel to refer to the following screen element in BriteCore:

Single sign-on

Spell out as single sign-on, with a hyphen between sign and on, on the first instance. Abbreviating as SSO is acceptable on second and subsequent instances, as long as the abbreviation is clear to the audience.

Single-tenant architecture

The phrase single-tenant architecture contains a hyphen between single and tenant.

Standalone

As an adjective, spell standalone as one word.

Example: Developers can build powerful integrations and standalone applications that communicate seamlessly with BriteCore.

Submenu

Use submenu instead of sub navbar or nav bar.

Sub navbar

Don’t use. Use submenu instead.

System

Use platform instead. Other acceptable substitutions, if they are accurate and sound good in context, include application, software, solution, and technology.

T

That

Avoid using the word that whenever you can. If a sentence makes sense without the word that, then do not use it.

Correct: The reason we decided to remove the word is because it’s unnecessary.

Incorrect: The reason that we decided to remove the word is because it’s unnecessary.

That versus which

That is sometimes necessary (though can often be written around). Use that at the beginning of a clause introducing information necessary for the sentence to make sense. Don’t put a comma before that.

Use which at the beginning of a clause that adds supporting or parenthetical information. If you can omit the clause and the sentence still makes sense, use which, and put a comma before it.

Correct: The module that enables you to add and edit contact information is the Contacts module.

Incorrect: The module which enables you to add and edit contact information is the Contacts module.

Correct: The Policies module, which includes robust search functionality, enables you to quickly locate and manage policies.

Incorrect: The Policies module that includes robust search functionality enables you to quickly locate and manage policies.

That versus who

Don’t use that or which to refer to a person. Use who.

Correct: Custom Setup is the best choice for customers who want to alter the standard Windows configuration.

Incorrect: Custom Setup is the best choice for customers that want to alter the standard Windows configuration.

There is, there are

Avoid expletive construction or sentences that begin with “There is” or “There are.” Rewrite such sentences to place the sentence subject in front of the verb.

Correct: Policy description options are Print Description and Additional Description.

Incorrect: There are two policy description options: Print Description and Additional Description.

Third party/third-party

Third party is spelled as two words without a hyphen when third modifies party. Third-party is spelled as a hyphenated word when it jointly modifies another word.

Examples:

Third party: Our mobile apps use the same API that third parties also use.
Third-party: The platform integrates with a wide range of third-party vendors.

This

Avoid using this as a pronoun, which can result in vagueness and confusion. Use this, instead, as a modifier for a noun.

Time zones

Write time zone as two words, not one.

Consider spelling out time zone regions for clarity, especially in external correspondence. See also Central Time.

Touch

Don’t use. Use tap instead.

Toward/towards

American English favors toward over towards.

Turn on, turn off

Use turn on and turn off to instruct users to turn a toggle key or toggle switch on or off.

Type

Use type when instructing a user to insert a value in a box. Do not use enter.

U

United States, United States of America

See US.

Up to date

Up to date is spelled as three words without a hyphen when it comes after the noun. Up-to-date is spelled as a hyphenated word when it jointly modifies another noun.

Examples

Up to date: BriteCore is always up to date.
Up-to-date: BriteCore is an up-to-date platform.

URLs

Brief URLs. When space is at a premium, such as on smaller marketing materials, using a truncated version of a URL that omits the protocol is acceptable.

Example: Learn more about provided hotel services at www.fourseasons.com/stlouis or reserve your room now at www.britecore.com/britecon.

BriteCore URLs. When providing BriteCore URLs, use the secure protocol (https) version of the URL, if it is available. Omit the trailing slash at the end of directory names.

Correct: https://support.britecorepro.com/vendors
Incorrect: http://support.britecorepro.com/vendors/

Note: Some BriteCore URLs don’t have an https equivalent, such as http://api.britecore.com/api.v2.html.

Client, product, and vendor URLs. When providing links to client, product, and vendor webpages and websites, double-check the URL, and use the secure protocol (https) version of the URL, if it is available. Omit the trailing slash at the end of directory names.

Correct: https://www.jetty.com

Incorrect: http://www.jetty.com/

YouTube URLs. When providing YouTube URLs, use the shortened version instead of the longer version.

Correct: https://youtu.be/wWwriAtiHQY
Incorrect: https://www.youtube.com/watch?v=wWwriAtiH

To find the shortened form of the URL:

  1. Open the desired video in YouTube.
  2. Select the Share tab, and the shortened URL appears.
  3. Select Copy to copy the shortened URL to the clipboard.

US

Abbreviate United States as US, without periods after either letter.

Username

Write as one word. Username, not user name.

Utilize

Plain-language guidelines recommend always replacing utilize with use.

V

Verbs

For search purposes in GitHub, always use simple verbs instead of gerunds for titles and headings.

Correct: Create a new template

Incorrect: Creating a new template

W

Want versus wish

Use want, not wish, in your writing.

Correct: From the dropdown list, select the state or province you want to use.

Incorrect: From the dropdown list, select the state or province you wish to use.

Wi-Fi

Spell Wi-Fi with an initial capital W, a hyphen, and an internal capital F.

X

[Add entries]

Y

You

In general, use second person, which means you write as though you’re speaking to the reader. Second person often uses the personal pronoun you, but sometimes the word you is implied. Using second person supports a friendly, human tone and helps avoid passive voice by focusing the discussion on the reader.

Examples

Create your own unique BriteCore experience.

You can set advanced options later if you need them.

Note: Consider omitting you can whenever the sentence works without it.

Z

[Add entries]

Sources