Technical terms come in a variety of shapes and sizes. Sometimes they’re everyday words that are given new meanings, like cloud, batch, or dashboard. Other times, common words are combined to create technical terms, like telemedicine or email. Over time, some technical terms become widely understood, such as BriteCore’s terminology and product names, but before that happens, they can be confusing to people who aren’t familiar with them. Use technical terms when they’re the clearest way to communicate your message, but use them with care. Be mindful of your audience—nontechnical users versus engineers, for example.
Important: When writing BriteCore software documentation, always use the correct names when referring to products and UI elements.
Use common words whenever possible: Don’t use a technical term when an everyday term will do. For example, don’t use rip to refer to copying files from a CD if you can use copy instead.
Don’t assume everyone will understand technical terms: When you must use technical terms for precise communication, define them in context.
Use technical terms consistently: When you’ve decided to use a technical term, use that term consistently across products and services, tools, websites, and marketing communications. Aim for one term, one concept.
Use BriteCore-specific terms where applicable: Use BriteCore and industry terms where applicable.
Don’t create a new term if one already exists: Don’t create a new term if an existing one serves your purpose. If you must create a new term, verify that it isn’t already being used to mean something else.
Research emerging terminology: Technology changes at light speed, and customers expect us to use the latest technical terms. But it’s crucial to use them correctly and consistently across our products, services, documents, packaging, and marketing. Before you adopt a new term in your content, find out whether other groups are using it, and how.
Guidelines
- Correct UI and product terminology
- Insurance industry terms
- Bias-free writing
- Reduce wordiness, increase clarity
- Describe interactions with the UI
- Write consistently about classic BriteCore and BriteSuite
Table 1: Incorrect UI terms and their correct equivalents.
| Don’t use | Use | Usage |
| Field Bar Space Area Line Text box | Box | In the Company box, type BriteCore. |
| Menu Left menu Navigation list Navigation panel | Sidebar Note: Sidebar is one word. | In the sidebar, select a product. |
| Drop-down | Dropdown Note: Dropdown is one word. | Select the Company dropdown. |
| dropdown menu Drop-down menu | Dropdown list Note: Refer to the dropdown and dropdown list distinctly; they aren’t the same thing. | In the Company dropdown list, select BriteCore. |
| Pop-up box | Pop-up window Note: Pop-up window isn’t synonymous with dialog box. Pop-up windows only provide information; dialog boxes are interactive. | After selecting Save, a pop-up window will appear, confirming the save. |
| Page Window | Screen | |
| Navbar Nav bar | Menu | |
| Sub navbar Sub nav bar | Submenu | |
| Dialog | Dialog box Note: Dialog box isn’t synonymous with pop-up window. Dialog boxes are interactive; pop-up windows only provide information. | |
| Modal | Dialog box Note: Modal is synonymous with dialog box, but we use dialog box for consistency and because it’s more familiar to non-techncial users. | |
| Enter Input | Type | In the Name box, type your username. |
| Hit Strike | Press | In the Name box, type your username, and then press Enter. |
| Check | Select | |
| Click | Select | |
| Search bar Search field | Search box | |
| Provider administrator portal Agent Portal | Provider Administrator portal Agent portal | Provider Administrator is capitalized. Portal isn’t. Agent is capitalized. Portal isn’t. |
| BriteSuites | BriteSuite | BriteSuite is never pluralized. |
| Classic BriteCore | classic BriteCore | Capitalize classic only when it begins a sentence, list item, or heading. Classic is not part of the BriteCore product name; it’s used to delineate which version of BriteCore is being discussed. |
| Touch (mobile) | Tap (mobile) | |
| Deselect | Clear, unselect | Clear your selections before saving. Unselect the Agent checkbox before proceeding. |
| Don’t use | Use | Use case |
| Insurer | Provider | |
| Producer | Agent | |
| Master agency | Agency group | |
| Sub agency | Agency | |
| Insured | Use the term insured to describe a person or entity (business) who falls under an insurance policy. | |
| Named insured | Use named insured only to describe a person whose name is listed on the policy. | |
| Involved party | A person identified as an owner, driver, or passenger on a claim. | |
| Other party | A person who isn’t identified as an involved party but is still eligible for coverage under the named insured’s policy. |
Be inclusive and mindful of diversity. Period.
Use gender-neutral alternatives for common terms.
| Use this | Not this |
|---|---|
| chair, moderator | chairman |
| humanity, people, humankind | man, mankind |
| operates, staffs | mans |
| sales representative | salesman |
| synthetic, manufactured | manmade |
| workforce, staff, personnel | manpower |
Don’t use he, him, his, she, her, or hers in generic references. Instead:
- Rewrite to use the second person (you).
- Rewrite the sentence to have a plural noun and pronoun.
- Use the or a instead of a pronoun (for example, “the document”).
- Refer to a person’s role (reader, employee, customer, or client, for example).
- Use person or individual.
If you can’t write around the problem, it’s OK to use a plural pronoun (they, their, or them) in generic references to a single person. Don’t use constructions like he/she and s/he.
| Use this | Not this |
|---|---|
| If you have the appropriate rights, you can set other users’ passwords. A user with the appropriate rights can set other users’ passwords. | If the user has the appropriate rights, he can set other users’ passwords. |
| Developers need access to servers in their development environments, but they don’t need access to the servers in Azure. | A developer needs access to servers in his development environment, but he doesn’t need access to the servers in Azure. |
| When the author opens the document …. | When the author opens her document …. |
| To call someone, select the person’s name, select Make a phone call, and then choose the number you’d like to dial. | To call someone, select his name, select Make a phone call, and then select his number. |
| If you want to call someone who isn’t in your Contacts list, you can dial their phone number using the dial pad. | If you want to call someone who isn’t in your Contacts list, you can dial his or her phone number using the dial pad. |
When you’re writing about a real person, use the pronouns that person prefers, whether it’s he, she, they, or another pronoun. It’s OK to use gendered pronouns (like he, she, his, and hers) when you’re writing about real people who use those pronouns themselves.
It’s also OK to use gendered pronouns in content such as direct quotations and the titles of works and when gender is relevant, such as discussions about the challenges that women face in the workplace.
Examples:
The skills that Claire developed in the Marines helped her move into a thriving technology career.
Anthony Lambert is executive vice president of gaming. With his team and game development partners, Lambert continues to push the boundaries of creativity and technical innovation.
The chief operating officer of Munson’s Pickles and Preserves Farm says, “My great uncle Isaac, who employed his brothers, sisters, mom, and dad, knew that they—and his customers—were depending on him.”
Do you have a daughter? Here are a few things you can do to inspire and support her interest in STEM subjects.
In fictitious scenarios, strive for diversity and avoid stereotypes in job roles. Choose names that reflect a variety of gender identities and cultural backgrounds.
In text and images, represent diverse perspectives and circumstances. Depict a variety of people from all walks of life participating fully in activities. Be inclusive of gender identity, race, culture, ability, age, sexual orientation, and socioeconomic class. Show people in a wide variety of professions, educational settings, locales, and economic settings. Avoid using examples that reflect primarily a Western or affluent lifestyle. In drawings or blueprints of buildings, show ramps for wheelchair accessibility.
Be inclusive of job roles, family structure, and leisure activities. If you show various family groupings, consider showing nontraditional and extended families.
Be mindful when you refer to various parts of the world. If you name cities, countries, or regions in examples, make sure they’re not politically disputed. In examples that refer to several regions, use equivalent references—for example, don’t mix countries with states or continents.
Don’t make generalizations about people, countries, regions, and cultures, not even positive or neutral generalizations.
Don’t use slang, especially if it could be considered cultural appropriation, such as spirit animal.
Don’t use profane or derogatory terms.
Do not use terms that may carry unconscious racial bias or terms associated with military actions, politics, or historical events and eras.
| Use this | Not this |
|---|---|
| primary/subordinate | master/slave |
| perimeter network | demilitarized zone (DMZ) |
| stop responding | hang |
Focus on people, not disabilities. For example, talk about readers who are blind or have low vision and customers with limited dexterity. Don’t use words that imply pity, such as stricken with or suffering from. Don’t mention a disability unless it’s relevant. For more information, see the Accessibility term collection.
Learn more For more information about writing that conveys respect to all people and promotes equal opportunities, see the Guidelines for Inclusive Language from the Linguistic Society of America.
One of the goals of our writing is that our readers understand BriteCore through our use of concise, informative language. In addition, we say our voice hinges on crisp simplicity. To these ends, it is important to avoid language/words that don’t add information and make your writing too wordy.
As with most elements of English, wordiness can be subjective. Ask yourself if the words and expressions you use add useful information to your sentences or needlessly lengthen them.
Examples of common expressions that can be written more concisely:
| Instead of… | …use this. |
| Have the option/ability/means to | Can |
| In order to | To |
| In order for | For |
| In order that | So |
| In regard to | About, concerning, on |
| In relation to | About, to, with |
| Pertaining to | About, of, on |
| In close proximity | Near, close |
| Each and every | Every |
| End result | Result |
| Exactly the same | The same |
| In spite of the fact that | Although |
| In the event that/of | If |
| In view of | Because, since |
| Refer back | Refer |
| Repeat again | Repeat |
| Revert back | Revert |
| A number of | Some, many |
| As a means of | To |
| At the present time | Now |
| For a period of | For |
| Has a requirement for | Needs, requires |
| In a timely manner | On time, promptly |
| Set forth in | In |
| The use of | (omit without replacement) |
| Take action to | (omit without replacement) |
| Time period | Period, time |
| With reference to | About |
| With the exception of | Except |
| In accordance with | By, following, per, under |
| Is authorized to | Can, may |
| Is applicable to | Applies to |
| It is requested that you | Please |
| Until such time as | Until |
| Pertaining to | About |
| Will have the [option/ability/means/etc.] to | Can |
You should omit or rarely use the following words. Many of these are adverbs, which are often unnecessary or add no additional useful information.
- Absolutely
- Actually
- Basically
- Certainly
- Completely
- Definitely
- Just
- Literally
- Much
- Probably
- Quite
- Rather
- Really
- Somehow
- Somewhat
- That (see usage dictionary)
- Totally
- Very
- Virtually
Write concisely
The following guidance will help you think about your choice of words and their meanings:
Avoid redundant categories.
- Specific words imply categorization.
- Winter is a season; you don’t need to say winter season—winter implies season.
- It is red instead of it is red in color—red implies color.
- Early instead of at an early time—early implies time.
- Round instead of round in shape—round implies shape.
- Software instead of software technology—software implies technology.
Avoid redundant pairs
- Many word pairs have similar meanings and one of the two words can stand alone without the other and without changing their meaning. If one word words instead of two or more, then just use one word.
- Beliefs instead of personal beliefs—is there a belief you have that isn’t personal?
- Fact instead of true fact—is there a fact that isn’t true?
- Gift instead of free gift—is there a gift that isn’t free?
- Bonus instead of added bonus—a bonus is always something that is added.
- Surprise instead of unexpected surprise—all surprises are unexpected.
Omit needless words
| Instead of… | …use this. |
| In order to | To |
| In order for | For |
| In order that | So |
| In regard to | About, concerning, on |
| In relation to | About, to, with |
| Pertaining to | About, of, on |
| In close proximity | Near, close |
| Each and every | Every |
| End result | Result |
| Exactly the same | The same |
| In spite of the fact that | Although |
| In the event that/of | If |
| In view of | Because, since |
| Refer back | Refer |
| Repeat again | Repeat |
| Revert back | Revert |
| A number of | Some, many |
| As a means of | To |
| At the present time | Now |
| For a period of | For |
| Has a requirement for | Needs, requires |
| In a timely manner | On time, promptly |
| Set forth in | In |
| The use of | (omit without replacement) |
| Take action to | (omit without replacement) |
| Time period | Period, time |
| With reference to | About |
| With the exception of | Except |
| In accordance with | By, following, per, under |
| Is authorized to | Can, may |
| Is applicable to | Applies to |
| It is requested that you | Please |
| Until such time as | Until |
| Pertaining to | About |
| Will have the [option/ability/means/etc.] to | Can |
| For the reason that | Because |
| Owing to the fact that | Because |
| Despite the fact that | Although |
| Of the opinion that | Think that |
| A total of | N/A |
| Of the belief that | Believe that |
| Make a connection with | Connect with |
| Have the capability/ability to | Can |
| Take into consideration | Consider |
| In terms of | By |
Example
Wordy: Lisa told other people that she was of the opinion that 100 winners would receive exclusive items despite the fact that the company had reduced its campaign budget.
Concise: Lisa said 100 winners would receive exclusive items despite the company’s reduced campaign budget.
Don’t use unnecessary intensifiers
Intensifiers are adverbs or adverbial phrases that bolster the meaning of other expressions and show emphasis. Words that we commonly use as intensifiers include absolutely, completely, extremely, highly, rather, really, so, too, totally, utterly, very and at all. These generally have no place in technical or business writing. Either omit the intensifier or give specific details, which may use more words, but you’re providing useful information.
Example
With intensifier: BriteCore makes managing your contacts really easy. (Really doesn’t say anything.)
Intensifier replaced and quantified: BriteCore makes managing your contacts easier through its intuitive search and editing features. (Now we better understand the nature of the easiness.)
No intensifier: BriteCore makes managing your contacts easy. (The original thought, in fewer words, saying the same thing.)
While not an exhaustive list, you should omit or rarely use the following words:
- Absolutely
- Actually
- Basically
- Certainly
- Completely
- Definitely
- Just
- Literally
- Much
- Probably
- Quite
- Rather
- Really
- Somehow
- Somewhat
- Totally
- Very
- Virtually
Exclude filler words like it, there, or want
Examples
- No place is like home (5 words) instead of There is no place like home (6 words).
- Listening to social media conversations is important (7 words) instead of It is important to listen to social media conversations (9 words)
Be mindful of nominalization
Nominalization is the use of of a word that isn’t a noun as a noun; that is, verbs or adjectives turned into nouns. They often end in -tion, -ment, -sion, -ance, or -al. For example, interference is a nominalization of interfere, decision is a nominalization of decide, and argument is a nominalization of argue.
Examples
| Instead of… | …write: |
| We want to ensure the development and improvement of our staff. | We want to ensure we develop and improve our staff. |
| Heating water to the boiling point causes evaporation. | Heating water to the boiling point causes it to evaporate. |
| Optimization of our workforce is a key goal of our company. | Our company wants to optimize our workforce. |
| Files his application | Applies |
| Reach an agreement | Agree |
| Enter into a collaboration | Collaborate |
| Conduct an investigation | Investigate |
Verbs are stronger, more powerful word choices.
Examples
Modern society is in need of a recalibration of its moral values.
Revision: Modern society needs to recalibrate its moral values.
Attempts by economists at defining full employment have been met with failure.
Revision: Economists’ attempts at defining full employment have failed.
Additional considerations and information
- Disregard words that explain the obvious or provide excessive details.
- Don’t overuse relative structures.
- Use active voice most of the time.
- Use simple past and present tense Instead of present/past perfect and present/past continuous.
- This is a similar issue. From essays to business documents to novels, it’s much more succinct to use simple present/past tense over any other tense, especially present/past perfect and present/past continuous. Why? Because doing so cuts down on unnecessary words, and, most of the time, you don’t need any of those other tenses because they’re clear through context. For example, change I have worked there to I worked there. Change He was surfing to He surfed. Nothing is different, right? There are exceptions, of course, but keep an eye on this issue, and you will find lots of instances where you don’t need those extra modifiers.
| Verb | Use for | Examples |
|---|---|---|
| Open | 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 or navigate to. Don’t use for commands and menus. | Open Photos. Open the Reader app. Select Users + groups to open the blade. Open the Filename file. To open the document in Outline view, select View > Outline. In WindowName, open the shortcut menu for ItemName. |
| Close | Apps and programs Blades Dialog boxes Files and folders Notifications and alerts Tabs The action a program or app takes when it encounters a problem and can’t continue. (Don’t confuse with stop responding.) | Close the Alarms app. Close Excel. Close the blade. Close the Users + groups blade. Save and close the document. Closing Excel also closes all open worksheets. |
| Leave | Websites and webpages | Select Submit to complete the survey and leave this page. |
| Go to | Opening a menu. Going to a tab or another particular place in the UI. Going to a website or webpage. It’s OK to use On the XXX tab if the instruction is brief and continues immediately. | Go to Search  , type the word settings, and then select Settings.Go to File, and then select Close. On the ribbon, go to the Design tab. Go to the Deploy tab. In the Configuration list … On the Deploy tab, in the Configuration list … Go to Example.com to register. |
| Select | Instructing the customer to select a specific item, including: Selecting an option, such as a button.Selecting a checkbox. 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. Selecting keys and keyboard shortcuts. (Document keyboard shortcuts only if they’re the most likely way the customer will accomplish a task or as an alternative input method, usually in a separate keyboard shortcuts article.) | Select the Modify button. For Alignment, select Left. Select the text, open the shortcut menu, and then select Font. Select Open in new tab. Select the LinkName link. Select F5. Select Shift+Enter. Select Ctrl+Alt+Delete. |
| Select and hold, select and hold (or right-click) | Use to describe pressing and holding an element in the UI. It’s OK to use right-click with select and hold when the instruction isn’t specific to touch devices. | To flag a message that you want to deal with later, select and hold it, and then select Set flag. Select and hold (or right-click) the Windows taskbar, and then select Cascade windows. Select and hold (or right-click) the Start  button, and then select Device Manager. |
| > | Use a greater-than symbol (>) to separate sequential steps. Only use this approach when there’s a clear and obvious path through the UI and the selection method is the same for each step. For example, don’t mix things that require opening, selecting, and choosing. Don’t bold the greater-than symbol. Include a space before and after the symbol. | Select Accounts > Other accounts > Add an account. |
| Clear | Clearing the selection from a checkbox. Synonymous with unselect in some instances. Don’t use deselect. | Clear the Header row checkbox. |
| Unselect | Removing the selection of an item, option, setting, etc. Synonymous with clear in some instances. Don’t use deselect. | Unselect the Agent option by selecting the radio button a second time. |
| Choose | Choosing an option, based on the customer’s preference or desired outcome. | On the Font tab, choose the effects you want. |
| Switch, turn on, turn off | Turning a toggle key or toggle switch on or off. | Use the Caps lock key to switch from typing capital letters to typing lowercase letters. To switch between Normal, Outline, and Slide Sorter views, use the buttons on the View tab. To make text and apps easier to see, turn on the toggle under Turn on high contrast. To keep all applied filters, turn on the Pass all filters toggle. |
| Type | Instructing the customer to type or otherwise insert a value, or to type or select a value in a combo box. | In the search box, type… In the Tab stop position box, type the location where you want to set the new tab. In the Deployment script name box, type a name for this script. |
| Move, drag | Moving anything from one place to another by dragging, cutting and pasting, or another method. Use for tiles and any open window (including apps, dialog boxes, files, and blades). Use move through to describe moving around on a page, moving through screens or pages in an app, or moving up, down, right, and left in a UI. | Drag the Filename file to the Foldername folder. Move the tile to the new section. Drag the Snipping Tool out of the way, if necessary, and then select the area you want to capture. If the Apply Styles task pane is in your way, just move it. |
| Zoom, zoom in, zoom out | Use zoom, zoom in, and zoom out to refer to changing the magnification of the screen or window. | Zoom in to see more details on the map. Zoom out to see a larger geographic area on the map. Zoom in or out to see more or less detail. |
Tabs
Because of layout differences between classic BriteCore and BriteSuite, instead of directing a user to select a tab, direct them to select the element name itself.
| Instead of… | …write: |
| Select the Processing tab. | Select Processing. |
Never refer to screens as tabs.
| Instead of… | …write: |
| On the Legacy Search tab, select Create a New Policy. | On the Legacy Search screen, select Create a New Policy. |
Internal tabs
For screens in BriteCore that use internal tabs (those not in the main navigation, but rather in the middle of a screen), refer to its instances in the main navigation instead, or identify and refer to the element by name without tab.
Example of internal tabs
Example of internal tabs reflected in the [Policies] menu
| Instead of… | …write: |
| Scroll to and select the Information tab, and then, under Contacts, select Add Another Named Insured. | Select Information in the Policies menu. Under Contacts, select Add Another Named Insured.
OR Select Information. Under Contacts, select Add Another Named Insured. |
Note: Use your best judgment for which approach will be clearest to the end user given the context of the documentation you’re writing.
Screen names
Don’t use the [Module] – [Screen] naming convention used in classic BriteCore. Screens aren’t titled this way in BriteSuite.
Classic BriteCore: Policies – Legacy Search
BriteSuite: Legacy Search
Therefore (examples):
| Instead of… | …write: |
| On the Policies – Legacy Search screen, select Create a New Policy.
(This is titled this way only in classic BriteCore.) | On the Legacy Search screen, select Create a New Policy.
(This works with what the user will see in both classic BriteCore and BriteSuite.) |
| On the Settings – Business Locations screen, in the System Wide dropdown list, select System Tags.
(Only classic BriteCore titles the screen as Settings – Business Locations. While both sites have dropdown lists, they are located in different places in each, and in full-demo, the System Wide dropdown list in the Settings menu is already expanded by default upon accessing the Business Locations screen, thus displaying the System Tags link without user interaction required.) | In the Settings menu, under System Wide, select System Tags.
(This works with what the user will see in both classic BriteCore and BriteSuite. Accessing the System Tags screen isn’t contingent on first being on the Business Locations screen. The System Wide submenu is already open when you access Settings, which is why this rewrite doesn’t indicate to first select it. Selecting System Wide in this instance would effectively hide the System Tags option.) |
| On the Settings screen, select the Modules dropdown list, and then select Lines. | In the Settings menu, under Modules, select Lines.
OR In the Settings menu, in the Modules submenu, select Lines. |
Menus
BriteCore menu
Refer to the main menu only as the BriteCore menu.
| Instead of… | …write: |
| In the top menu, select Lines. (The menu isn’t always on top.)
In the main menu, select Lines. In the side navigation, select Lines. (The menu isn’t always on the side.) In the sidebar, select Lines. (The menu isn’t always a sidebar). In the navigation, select Lines. (This isn’t clear. There are multiple navigation levels.) | In the BriteCore menu, select Lines.
OR Select Lines. |
Note: Exceptions such as BriteApps’ Navigation Menu, where the menu name is titled on the screen, are still acceptable.
Secondary (module-level) menus
Refer to module menus by name when applicable. This isn’t required, but can add clarity. Use your best judgment.
Note: Don’t refer to module menus (Contacts, Lines, Policies, Claims, Reports, Settings, etc.) as submenus.
Acceptable examples:
- Select Lines. In the Lines menu, select Notes.
- Select Lines, then select Notes.
Tertiary menus (submenus)
Some modules, such as Policies, have a tertiary menu (Payments).
While not required, you can refer to this menu level as a submenu.
Acceptable examples:
- Select Policies from the BriteCore menu. Select Payments. In the Payments submenu, select Daily Cash Receipt.
- Select Policies, then select Payments. Select Daily Cash Receipt.