Since our macros are broken.... Here are all the glossary notes that should be part of our documentation style-guide.

We may want to break these into... Alexandria-specific terminology, vs – punctuation – formatting — word choice, writing style rules

-

Add-on. Software integration that adds functionality to a larger program. Always hyphenate.

Barcode. Always one word.

Basic info pane. The main pane in Items/Patrons Management that contains the most important information for each item or patron. Unlike the Details pane, this pane doesn't have tabs and is always displayed.

Basic search vs advanced search. Basic Search consists of the search bar and dropdown menu above the Record List in Patrons and Items Management. It offers operators a quick way to search for items or patrons.

Customer Support. When referring to customer support for an individual brand, use the brand name and capitalize Customer Support. For example: KeepnTrack Customer Support. — Use support representative to refer to a customer support user. Don't use rep, support rep, customer support representative, support agent, or customer support agent.

Call number. A group of letters and/or numbers that identify specific items in a library and provide a way for organizing library holdings. Two major types of call numbers are Dewey Decimal Call Numbers and Library of Congress Call Numbers. Only capitalize when directly referring to a field name.

Catalog. A database (either online or on paper cards) listing and describing the books, journals, government documents, audiovisual, and other materials held by a library. Various search terms allow you to look for items in the catalog.

Circulation. An Alexandria module/area used to perform general library actions, such as checking books in and out; placing hold requests and reservations; processing fees, fines, and payments; and more. Never use "Circulation Management."

Cloud-Hosted. A type of setup in which the customer's data is stored and backed up on COMPanion servers. As opposed to Self Hosted, where the customer stores their own data. Cloud Hosted should be used without a hyphen, except as a descriptor, where it would be cloud-hosted data.

Drag-and-drop. Use as an adjective, not a verb or noun. For example: Drag-and-drop editing, a drag-and-drop feature. Use drag by itself as a verb. The action of dragging includes dropping the item in place. For example: Drag the item to another day of the week.

Ebook. CMOS, AP, Merriam-Webster, and other official style books and dictionaries still use the hyphenated e-book. However, the general public is moving towards the non-hyphenated term, which has been far more popular over the years. For our purposes, we will use ebook in a general sense and Ebook in headings. Reference: https://www.marketsmiths.com/2017/ebook-vs-e-book-vs-ebook-guess-spelling-got-twice-many-clicks/

e.g. Abbreviation for for example. Not to be confused with i.e.

Email. Use email, not e-mail, E-mail, or E-mails. Use emails as the plural. Acceptable for use as a noun or verb.

Internet. Do not capitalize internet.

Icon. An icon is an image or picture used as a visual representation.

JavaScript. One word. Capitalize the J and S.

Materials. Used as an encompassing term when referring to a library’s collection: book, video, ebook, etc.

Null. When using "null," mention whether you're referring to the concept of empty or the literal value null.

Not Supported. Use "not supported" to describe a feature that is available but doesn’t have any associated help and is used at the user’s own risk.

Receipts. Should be referred to as receipt printer, not slip printer.

Patrons. Patrons are the users (students, librarians, etc.) of Alexandria. Operators ARE patrons, though at times it may be more appropriate to refer to a patron with higher security access, such as an administrator or a librarian, as an operator since they are operating or managing the system as opposed to simply using it.

Pane. A section of a module/area. Two examples in Alexandria include the Current Patron and Current Item panes in Circulation.

Preferences. Preferences is the in-app area/hub that links to a bunch of grouped preferences. In general, preferences control site-wide or multi-site app customizations/settings. "Security Preferences," "Barcode Preferences," and "Extras Preferences" are all examples of how to refer to specific preferences.

Radio buttons. A user interface control that offers several mutually exclusive options. Users can select only one of the options. For radio button fields on a record, follow the guidelines for Field Names. For radio button settings on Setup pages (which tend to be lengthy), use initial caps.

Record names. Don't capitalize record when used as part of a name, unless in a heading or considered part of the proper name.

Report names. Use title-style capitalization. Don't capitalize report unless it's part of the report name.

Researcher. Alexandria Researcher is our patron-facing module/area. It allows patrons and operators to choose the interface they want to use—Search, Scout, or Explore—to search the Alexandria database. "The Researcher" is not necessary. Simply use "Researcher."

Reports. Alexandria’s Reports area allows you to create reports that only include pertinent information: records of interest, transaction types, balance elections, and personalized text on circulation notices. You can also schedule reports and deliver their output via email, FTP, etc. Capitalize when referring to the module. Do not capitalize when referring to an individual report or to reports in general.

Record list pane. The left-hand side of Items and Patrons Management contains the Record List pane, where all item or patrons records matching a user's search criteria will be displayed in the user-specified sort order.

Researcher pane. The explore pane used in the Researcher Hub.

Researcher Hub. The Researcher landing page. /researcher

Subtab. Don't capitalize in general usage. For example, it would be "Payments subtab" instead of "Payments Subtab." Use sentence case capitalization for subtab names.

Services. Things customers purchase from us, such as training, Cloud-Hosted services, technical support services. It can also be used as a technical term relating to the capabilities of the server and how its clients initiate server operations.

Site. A site is an individual library or school. Site preferences are local and only affect one database. Site ID is the official term as of 20220310. Not Site ID Code, or Site Code. You can call it a site code though.

System. global; things that affect more than 1 database

System Patron. They should always be considered System Patrons; being “special” has too many unfavorable connotations.

Self-hosted. Self Hosted (previously Alexandria Customer-Managed, then Self-Hosted). When customers purchase Self Hosted (On-Premises) and various Alexandria licenses, they are responsible to install, define DNS access, update, and backup themselves. In other words, customers must manage their own installation and operations. As opposed to Cloud Hosted where we manage their data. Self Hosted should be used without a hyphen, except as a descriptor e.g. "your self-hosted servers".

Snackbar. Snackbars inform users of actions the app has performed or will perform. They appear temporarily at the bottom of the screen.

Sidenav. The sidenav is the navigation menu on the left side of the screen. It contains links to major modules/areas and displays randomized app tips at the bottom. It can be collapsed or expanded.

Sort menu. A dropdown menu that allows the user to specify how results or information is sorted. Patrons and Items Management each have a Sort dropdown above the Record List.

Sort order(?). A button that allows users to choose between a descending or ascending sort order for the Patrons/Items Management Record List's results. It's located above the Record List and is represented by an icon consisting of an A, Z, and arrow.

Settings. Settings are lower-level sets of individual preferences; they are not usually used site-wide. These include Self-Service and Activity station settings, Patron Status avatars, and operator account settings.

Touchscreen. One word. A touchscreen is an electronic visual display that detects the presence and location of contact with its surface, so that users can manipulate a device’s interface by touching the surface with a finger or stylus. Many popular mobile touchscreen devices are equipped with multi-touch technology, which means the touchscreen can recognize the presence of two or more points of contact.

Tips. Tips are randomized pieces of information or advice that appear at the bottom of the sidenav. You can hide or show tips. Internally, note that these tips are pulled from the Message Center.

User menu. The User menu is located in the Librarian topnav and contains dropdown links/options to Patron Status, Site, and Log Out. The dropdown can be opened by clicking on the operator name, site, or picture.

Window. A window is a specific view from within a module/area. All windows combine to make the module/area.

 z39.50. Z39.50 Services is a built-in server/client, making it easy to share your own resources with others in your district or community and allowing patrons to access your data from community locations running Z39.50 clients. Special consideration may apply when running multiple Z39.50 servers from multiple hosted Data Stations in a single IP environment.

Versioning. 

For API and product version numbers: 

• Use "earlier" instead of "lower" or "below," as in Internet Explorer 6.0 and earlier.
• Use "later" instead of "above," as in Internet Explorer 7.0 and later.

check in, check out, checkout

PHRASAL VERB: check in / check out

PAST TENSE: checked in / checked out

PRESENT PARTICIPLE: checking in / checking out

ADJECTIVE/NOUN: check-in / check-out

NOTE: For KeepnTrack, it’s ALWAYS ‘Sign in/out’ a student, never ‘check out’ a student.

dialog

A “temporary window” displayed on top of the current window.

Dialog headings should have sentence-style capitalization.

Dialog action buttons should be a single word. Use two-word buttons only when unavoidable.

-

Use "popup window" to describe a new, separate browser window that opens during an action on a page. Use title-style capitalization for popup window names. Popup is always one word; never hyphenate. 

For example: "Click a custom button to display a record in a popup window."

dropdown menu

A menu that, when clicked, a list of items drops down. Never pulldown menu.

Submenus are nested within menus and are indicated by right-pointing carats.

"Dropdown" alone can refer to the unopened menu.

App. 

Use app unless you’re referring to:

• The Alexandria application. Use just Alexandria, if the context is clear.
• A part of a license, permission, or product name, such as in “Customize Application” permission or License Management Application

modules & areas

The external, user-facing term for modules, which are logical “sets of windows” designed for a specific function. These include Circulation, Items Management, Patrons Management, Inventory, and more.

In most cases, the word "area" itself is unnecessary. Instead of "Open the Inventory area" you can instead say "Open Inventory".

-

There are two definitions for "module:"

1. A logical “set of windows” (see above) designed for a specific function. Inventory is a module, Self-Service is a module—these use a number of windows used to formulate an interface for a particular function. Modules should only be used for special purpose interfaces that are mostly independent. In most cases, the word "module" itself is unnecessary. Instead of "Open the Inventory module" you can instead say "Open Inventory".
2. An add-on that doesn't automatically come with the software (such as Activity).

Note: For the first definition, you should only use the term "modules" internally. For all patron-facing content, use the term "areas" instead. The second definition is sometimes used in Sales/Marketing materials.

backup & back up

A copy of computer data (such as a file or the contents of a hard drive). Also, the act or an instance of making a backup.

Example: Back up your data regularly; then you’ll have a backup when your hard disk crashes.

A backup is a copy of your archive folder that is saved to an external medium such as an external hard drive, flash drive, network file server, or a backup service on the cloud. You should perform at least one backup any day your data is modified. We never discourage customers from keeping additional backups. If you are using the same drive to store all the backups, remember to rename each saved data folder to include the date (e.g. Jan012018Data, or 04292018Data).

button

A user interface control that can be clicked on to perform a certain action within the app (add, delete, print, edit, etc). Typically, buttons are any user interface control or text you can click on that's not a dropdown menu or link.

Buttons should have sentence case capitalization.

A "button" may also refer to an Explore button, which consists of an icon, descriptive label (located below each icon), and associated action that is performed when the button is clicked in an Explore pane.

click

All references to mouse clicks assume that the user has configured the left mouse button as the primary mouse button and the right one as the secondary.

• Click means click the left mouse button.
• Right-click means click the right mouse button.
• Don’t use click on. Correct example: "Click Merge to finish."
• Don’t use click when describing gestures users perform in a mobile app with a touchscreen interface.

data station

The server/computer/piece of hardware that houses Alexandria or Textbook Tracker database(s).

• Centralized Catalogs, Alexandria Controllers, and standalone catalogs have one data station.
• Distributed Catalogs have separate data stations for each database.

This term is always decapitalized and two separate words.

database

Contains sites (library collections) and everything Alexandria/Textbook Tracker needs to work (ALX.db, GlobalConfig.json, Log.db, Operation Files, etc).

• Centralized Catalogs have one database that contains every single site on one data station.
• Distributed Catalogs have separate databases for each site on separate data stations.
• Alexandria Controllers have separate databases for each site on one data station.

A database is sometimes called a data folder/file internally. However, the user-facing term in our Support Centers is database.

This term is always decapitalized.

field

A field is any area in which a user can type or add their own text.

Use title-style capitalization for field names. Don't capitalize field when it is part of a name, unless it’s in a heading or considered part of the proper name.

• When referring to fields in relation to objects, use on instead of in.
• Don't use quotation marks for these values. For example, when you create a custom field on a standard object, add the custom field to your package explicitly.

Field help text should have sentence-style capitalization.

field names

For topics that list all of the fields in a detail page, use the following standardized text: “The <object name and type> has the following fields, listed in alphabetical order.” If it includes fields that can be hidden in page layouts or field-level security, include the following standardized text: “Depending on your page layout and field-level security settings, some fields may not be visible or editable.”

• LABELS. Use the element's exact label when you refer to user interface elements, but remove any end punctuation. Retain any punctuation that's not at the end of the label. Example: Click Add to browse for files on your local computer.

• CAPITALIZATION. Use title-style capitalization for field names. Don't capitalize "field" when it's part of a name, unless it's in a heading or considered part of the proper name. Example: Import your data into the Lead Source field.

• FORMATTING. In documentation, field names display in a monospace font. In user interface text, don't use special formatting when referring to field names. When listing fields with descriptions, use a table. Don't use a bullet list or definition list.

• CUSTOM FIELDS. When referring to a custom field that you recommend users create, use the same style conventions as when referring to a standard Alexandria field.

• PREPOSITIONS. When referring to fields in relation to objects, use on instead of in. Example: When you create a custom field on a standard object, add the custom field to your package explicitly.

file name

File name is always two words. Use the following style guidelines for file names and file extensions.

• For file, directory, and drive names, use the exact spelling and capitalization used in the program or file itself.
• Use all lowercase for file extensions. For example, Word adds .docx to a file name if you neglect to specify the file format when saving. Refer to the Microsoft Manual of Style for Technical Publications. 
• If you can't avoid using the file extension to describe the file, precede the extension with a period; for example, “a .zip file.” 
• If the extension displays within a sentence, use lowercase; for example, “A .txt file that is renamed to .rtf is not searched.” If the extension displays within a heading, use title case; for example, “Renaming .Txt Files.”

file type & extensions

For file, directory, and drive names, use the exact spelling and capitalization used in the program or file itself. Use all lowercase for file extensions. For example, Word adds .docx to a file name if you neglect to specify the file format when saving.

When referring generally to a file extension type, use all uppercase without a period. Add a lowercase s to make plural.

• GIF
• PDF
• HTML
• JPGs

When referring to a specific file, the filename should be lowercase:

• slowclap.gif
• MCBenefits.pdf
• ben-twitter-profile.jpg
• ilovedonuts.html

PDF: Always capitalize. Add a lower-case s to make plural: PDFs.

 Hover

Use "hover" instead of "mouse over" to describe moving the mouse pointer over an icon, field, or button.

Write "hover over" instead of "hover your mouse pointer over."

install

Use install only as a verb, never as a noun. 

Correct: Install the software on your computer. 

Correct: Finish the installation before you proceed. 

Incorrect: Finish the install before you proceed.

iOS

One word. Capitalize only the O and S. iOS is the name of the operating system that runs on Apple’s line of mobile devices: iPad and iPhone. When specifying a version of iOS, append the version number but don’t include the word version: "iOS 5.0."

iPad: One word. Capitalize only the P. 

iPhone: One word. Capitalize only the P. 

Avoid pluralizing the names of Apple’s mobile products: 

Incorrect: iPads and iPhones 

Correct: iPad and iPhone devices

keyboard shortcut

Use "keyboard shortcut" or "shortcut" in reference to all keyboard shortcuts that aren't Circulation commands. The word "hotkeys" is now obsolete.

Formatting:

• Don't format key names in bold.
• Use title capitalization for key names, as in Alt or Right Arrow.
• Use the verb Press instead of Click or Hit, as in "Press Ctrl."
• Use a plus sign, as in Ctrl+P, to indicate key combinations.
• Don't include a space before or after the plus sign.

login / log in

Login: (noun) This refers to the combination of a customer's username and password.

• Do you know your login information?
• Enter your username and password on the login page.

Log in: (verb) This refers to the action of entering a username and password to gain access to an account.

• Did you log in?

Log in to: (verb) "Log in to your account." The word in belongs with log. They are logging in. The word to is a preposition to tell the customer where the action of the verb takes place. Where did the customer log in? The account.

• Please log in to your account.
• Log in to Alexandria.
  

Log into: (verb) I can't think of a situation where you would use this here. Into indicates a physical motion or direction.

• Place the log into the fire.

Note that you "log in" to KeepnTrack admin, but visitors "sign in" to kiosks.

links

In UI text, don't use any special formatting when referring to link text.

• Capitalize link text based on context. For example, if link text includes an element that is capitalized in the UI, capitalize it in the link text too.
• Don’t list the following UI element types unless needed for clarity or navigation: button, checkbox, drop-down list, field, icon, menu, link, radio button, or window. For example, write Click Save , not Click the Save button.

press

Use "press" as a verb to describe the act of striking keys on a keyboard or of pressing a button on a mobile device. 

Examples: 

• Press CTRL. (keyboard) 
• Press the menu key. (BlackBerry)
• Press the Home button. (iOS)

setup, set up

Setup is a noun or an adjective. Set up is a verb phrase.

• Setup: noun or adjective used when referring to computers and their setup
• Go to the setup screen. [adjective]
• This PC's setup is rather odd. [noun]

• Set-up:  noun  'the set-up'
• It was a complete set-up from start to end!
• The set-up of this children’s climbing frame is so tricky.

• Set-up: adjective that refers to things which are NOT referring to computers and their setup
• The bank account attracted a $10 set-up fee.
• The set-up time was extremely short.

• Set up: verb 'to set up'
• You must set up your computer.
• To set up your stall now would be most wise.
• He was told lies and was completely set up.

sign up, sign-up

Sign up is a verb. Sign-up is an adjective or noun. Don't use signup. 

For example:

• When you sign up, choose your template.
• During sign-up, choose your template.
• The sign-up process is easy.

select

The proper term to use when describing an action involving choosing an option from a dropdown menu, a radio button selection, or a checkbox. “Check” is not correct.

tab

An interface component that lets you navigate around an app. A tab serves as the starting point for viewing, editing, and entering information for a particular object. When you click a tab at the top of the page, the corresponding tab home page for that object appears. A tab can be associated with an object, a Web page, or a Visualforce page.

• Capitalize the names of all tabs in the application using sentence case. Refer to them using the exact spelling in the user interface. For example: Accounts tab, not Account tab. Don't capitalize tab in general usage.
• When describing an action on a tab, use "on the tab_name tab," not "in the tab_name tab."
• In the UI, add “ - Selected” to the hover text for the selected tab; for example, Accounts - Selected.

web

wi-fi

Hyphenate. Capitalize the W and the F.

Wi-Fi™ is a registered trademark of the Wi-Fi Alliance and the brand name for products based on IEEE 801.11 standards. Use Wi-Fi when referring to the wireless connection on a mobile device or to wireless networks.

Writing tips / word choice:

Using active voice.

e.g. 'allow' or 'let':

Avoid. Try to restructure the sentence so the reader is the subject.

Avoid: Alexandria allows you to customize Explore Builder panes.

Better: You can customize Explore Builder panes.

-

Changing passive voice to active usually makes a sentence clearer and less wordy. Passive voice can be appropriate in some cases.

https://www.grammarly.com/blog/a-scary-easy-way-to-help-you-find-passive-voice/

-

Use active voice whenever possible. Be careful not to change the meaning of a sentence when rewording from passive to active voice.

Passive voice can be appropriate in some cases. For example,

• When active voice creates an awkward construction
• The subject is unknown or not the focus of the sentence
• You want to avoid blaming the user
• To convey an impersonal tone for a technical audience

Here are some strategies and examples for changing passive voice to active voice.

The data is entered by the user.

When you create an action, its layout is populated with a default set of fields.

The user enters the data.

When you create an action, Alexandria populates its layout with a default set of fields.

If you want to place a frame script on a tween layer, it must be created on another layer and dragged to the tween layer as well.

To place frame scripts on a tween layer, create them on another layer and drag them to the tween layer.

Is a technology the subject of the sentence? Sometimes the active voice is awkward, and the passive voice is better.

The variable is passed in the URL. Convert a field’s type from one that’s supported for actions to one that isn’t supported.

past tense

Use present tense whenever possible.

imperatives

In help documentation, use imperatives whenever possible. In UI text and both user and developer documentation, "you" or an imperative is almost always appropriate in procedures, since the person reading the documentation is usually the same person trying to perform the task.

Always use imperatives in task topic titles.

Time

For time values in a twelve-hour system, use AM/PM preceded by a space. Time zones, where needed, are given in parentheses. Example: 10:30 PM (MST).

Don’t use A.M., P.M., a.m., p.m., am, or pm.

(CMOS 10.41)

-

For time values in a twelve-hour system, use AM/PM. preceded by a space. Time zones, where needed, are given in parentheses. For example, 10:30 PM (MST). Don’t use A.M., P.M., a.m., p.m., am, or pm.

date

Don't use st, d, and th after numerals in dates to indicate ordinals: April 15, not April 15th. Use commas with full dates:

"On December 14, 2009, the group attended the meeting."

Use an en dash with date ranges: "2004–2010."

& ampersand

Use an ampersand (&) only when screen real estate is an issue or when it's part of a company name, logo, proper noun, or title. Otherwise, spell out "and".

affect/effect

Affect (verb): to influence.

• Example: Calendar sharing settings affect the visibility of items on a calendar.

Effect (verb): to bring about.

• Example: Effect change. Don't use effect as a verb in technical documentation.

Effect (noun): result, outcome (avoid).

• Example: Changes take effect immediately.

be sure to

Be sure and is colloquial. Use be sure to in technical writing.

(Handbook of Technical Writing, p. 47)

comprise vs compose

Comprise means “contain” or “include.” Compose means “constitute; to form by putting together.” The difference between comprise and compose is that parts compose the whole, while the whole comprises the parts. For example, “The book Comprises 24 chapters.” “Knowledgeable engineers compose the committee.” Avoid comprised of (one way to remember is you wouldn’t use “include of”).

can/could

Avoid the modal verbs could, may, might, and should in technical documentation. Modal verbs are ambiguous and leave the reader wondering what to do. 

• Can means the ability to do something. Avoid could.

display/view

Use display to describe what a Web browser or the app does. Use view to describe what a user does. For example: Choose which related lists will display on your detail pages. You can view related items in related lists. 

disabled

• Unavailable: Use for a menu item, dropdown list option, or other selection that is currently unusable: Some options may be unavailable depending on your license type. >> except we use Disabled for this. "The field is disabled when the record is locked."

• Disable: Use to describe the act of making something unavailable: Select Disable to disable task alerts.

• Disabled: Use for a feature that is not enabled: Email-to-Case is disabled on sandbox.

em dash

Don't add a space on either side of the em dash. Use an em dash to:

• Introduce an element added to give emphasis or explanation by expanding a phrase in the main clause of a sentence: These users have the same access to your data as you do—they have access to all data you own or that has been shared with you.

• Indicate a bigger break in thought than that represented by a comma.

• Define or enumerate complementary elements that are added to or inserted in a sentence: If you use the template for any other email alert action—in either workflow rules or approval processes—the merge fields return a null value.

• Separate pronoun referents from the subject of a final, summarizing clause: Latin, Cajun French, and UNIX—these are the languages she most admires

en dash

Use the en dash to indicate a minus symbol or ranges for numbers, dates, and time. Don't add a space on either side of the en dash. For example:

• 1981–88
• pages 38–45
• –24

To insert an en dash in Confluence, type two hyphens and a space—but then remove the spaces on either side of the en dash.

Use a hyphen instead of an en dash in compound words like user-friendly.

• To insert an em dash in Confluence, type <ALT+0150>.

etc. Don't use in documentation or UI text. Rephrase to provide more specific information. >> eh, we can use this...

When adding an inline example, introduce it with for example. Don't use e.g., i.e., or example:

"For some organizations whose instances migrated (for example, from na7.salesforce.com to na10.salesforce.com), fixed an issue that prevented users from logging into Salesforce for Outlook successfully."

"For example, if a customer reports a problem that you can't solve during the chat, create a new case for the customer."

fewer / less

Less refers to quantity while fewer refers to number.

For example:

• We recommend fewer than five filters.
• Smaller organizations receive less than 1 GB of storage.

Be aware of your meaning. "I have less problems than they" means my problems aren't as big, whereas fewer problems would mean that mine aren't as numerous.

first person +

Don't use I. We is acceptable.

For example: "We recommend that the file size be under 50 KB."

See also Second Person, Third Person.

-

For user documentation and UI text, use the second person, you, which makes the writing more informal and personal.

• In user documentation, use the imperative voice whenever possible.

• Select the Tag checkbox to enable tagging.
• Download library resources from the Alexandria website.

• Omit You can when possible as it unnecessarily increases word count.

• Use the third person when the information isn't directed at a specific user, though this sometimes means using the passive voice. For example: If this header isn't used or the value of its element is null, the opportunities are transferred to the forecast manager in the specified territory.

• Be aware of the various, possible contexts for the information. Some text is extremely sensitive to context, and procedures or explanations of how a feature or component works must be written with different user contexts in mind. This is because the person reading the documentation is most likely not the one issuing the command or method under discussion. Developers may read information that they need to know to write a client program that actually executes the command, so phrases like you or your organization aren't always right.

following

Don't use in UI text to describe the location of an element on an application page.

Avoid using in documentation to describe the location of an element (“The following table” or “The following diagram”). Instead, refer to the element directly. For example, “This table” or “The diagram.” If necessary, use "later" or "following" instead of "below" to indicate upcoming information in documentation.

he/she

Okay to use. In fact preferred to a generic-"they" because more specific examples are better. ("They" as a non-gendered person is ok, if you are talking about the Nickname field or something. )

has been / was

I was a teacher in Korea for 15 years. = but not now 

I have been a teacher in Korea for 15 years. = and I still am.

"That is" example: "Remember to map custom lead fields to other custom fields of the same data type, such as mapping numeric lead fields to other numeric fields. Enclose an expression, such as that is or namely, and the element it introduces in parentheses only if a comma doesn't signal a big enough break in continuity."

Not to be confused with e.g.

introductions

Don't add an introductory phrase (also known as a stem) to a task or table that appears soon after a topic’s title. For example, a set of steps that immediately follows the title Editing a File does not need the introductory phrase “To edit a file:”. If you include only essential introductory content in a task, you’ll never need a stem.

italics

Use italics for emphasis, but don't overdo it. Avoid using italics in on-screen text, as italic text is hard to read. In documentation, use italics for specific references to the titles of manuals, books, magazines, disks, videotapes, films, audiotapes, catalogs, bulletins, and promotional literature.

jargon / cliches

Avoid jargon and cliches, which are words and phrases that have become trite and ineffective through overuse. Here are some examples: 

• Cutting edge
• Ease of use
• General-purpose
• Grow your business
• Hands-on
• Innovative
• Intuitively
• Leverage (as a verb)
• Paradigm
• Powerful feature
• State-of-the-art
• Robust
• User-friendly
• Total solution

Try to find words that convey your idea more effectively. 

Translate technical jargon into simple words whenever you can. Even when the reader is highly skilled, plain English may still do the best job of communicating. When you cannot use simple words, define or explain them. 

If technical terms are appropriate and necessary for your audience and purpose, make sure they're defined clearly and used consistently.

just

Don't use it. << this is a simplification. Use it sparingly. Often it can be removed. 

"Just" makes me feel like an idiot. "Just" presumes I come from a specific background, studied certain courses in university, am fluent in certain technologies, and have read all the right books, articles, and resources. "Just" is a dangerous word. -- "Just" by Brad Frost

later

Use "later" instead of "above," as in Internet Explorer 7.0 and later. If necessary, use "later" or "following" instead of "below" to indicate upcoming information (later in this guide).

latin abbreviations

Use full phrases or abbreviations. When giving an in-line example, use "for example" rather than "e.g.".

namely

that is

in other words

i.e.

less / fewer

Less refers to quantity while fewer refers to number. For example:

• We recommend fewer than five filters.
• Smaller organizations receive less than 1 GB of storage.

Be aware of your meaning. The sentence I have less problems than they means my problems aren't as big, whereas fewer problems would mean that mine aren't as numerous.

lists / bullet points 

Lists organize categories of information or highlight important elements. Run-in lists present a series of enumerated items in running text; displayed lists present bulleted or ordered items on separate lines for greater visual effect and readability. Bulleted lists are best used to highlight items that may appear in any order; ordered lists indicate priority ranking or sequencing.

:

• The available objects are:
  • Accounts
  • Opportunities
  • Quotes
• If errors are preventing you from adding one or more Data.com records to Salesforce, we’ll provide a .csv error log file. How we provide the error log depends on what you were trying to do.

  • If you were trying to add fewer than 200 records, you’ll see a message with a link to the error log on the Files tab.

  • If you were trying to add 200 records or more, you’ll receive an email with a link to the error log on the Files tab.

  • If you were trying to add any number of records and you do not have Chatter enabled, you’ll receive an email with the error log attached.

• Keep items in a series, list, or table parallel. Don't mix fragments and full sentences.

• When introducing a list, don’t refer to the number of items in that list. Doing so could cause errors if list items are added or deleted.

• Use an initial cap for the initial word of each line item, whether a fragment or a full sentence.

• Omit the period after items in a bulleted or other type of list only if the items are fragments rather than complete sentences. However, a period is necessary at the end of a sentence whenever more than one sentence exists for that bullet. In this case, make all bullets complete sentences that end in periods so that each bullet is parallel.

• Focus on users' tasks; write only what is necessary for users to complete them.

• Keep tasks short.

measurements

•  Repeat the unit of measure for two or more quantities. Between 32 KB and 100 KB.
• It's acceptable to abbreviate measurements, as in KB and GHz, if the abbreviations are common to the audience.

• In abbreviations for measurements, don't add an s to indicate plurality. For example: 10 oz or 30 mm

• When a measurement is used as an adjective, use a hyphen to connect the number to the measurement, as in 10-point type. Otherwise, don't use a hyphen.

• Don't use periods with abbreviations for units of measure. If the abbreviation forms a word, such as in as an abbreviation for inches, spell out the word in text to avoid confusing the reader. Confine use of the abbreviation to tabular matter and other condensed copy.

mobile device

Use mobile device when referring generally to handheld computing devices—and not specifically to a type of Android, Apple, or BlackBerry device—because the term can include both smartphones and tablets. (Example: The Chatter mobile app lets you collaborate in Chatter from your mobile device.)

After first mention in a topic, just use device.

may, might, must

Avoid the modal verbs could, may, might, and should in technical documentation. Modal verbs are ambiguous and leave the reader wondering what to do.

• May means permission to do something. Avoid may. We rarely indicate permission to do something in the documentation. Use can for the ability to do something.

• Might means it’s possible to do something. Avoid might and use an imperative instead. For example, instead of saying “You might consider XYZ” use “Consider XYZ”.

• Must means it’s necessary to do something. Avoid should. Use must for necessity or rephrase as “We recommend...” to tell a customer to do something.

 navigation

In documentation, use bold font and a symbol, such as a bracket (>), to display menu option selections or sequences of user interface clicks. For example, File > Print indicates that a user selects the Print option from the File menu.

• Don’t list the following UI element types unless needed for clarity or navigation: button, checkbox, drop-down button, field, icon, menu, link, radio button, or window. For example, write Click Save, not Click the Save button.
• In UI text, provide a direct link to a described page instead of a sequence of menu options. If that’s not possible, use the same style convention as documentation.
• Use title-style capitalization.

negatives

Whenever possible, phrase sentences positively rather than negatively.

Negative: The mini view doesn't display if the record in the detail view doesn't have any records associated with it.

Positive: The mini view only displays if the record in the detail view has records associated with it.

numbers

• Spell out numbers:
  
  • At the beginning of a sentence: Twenty-five people were part of the development team.
  • If the number is fewer than 10: Of the seven systems, the administrator backed up six daily. This rule applies unless the number precedes a unit of measure.
  • When depicting approximate numerals in hundreds or thousands: The managed forest contained about six thousand trees.
• Use numerals:
  • For numbers 10 or greater.
  • For approximate numbers above 999,999, use the numeral followed by x`“million” or the appropriate word instead of all the zeros: The solar system is estimated to be about 4.5 billion years old.
  • For specific round numbers, such as 34,000 and 200,000, use the full numeral, including the zeros. Don't use “thousand”: Custom views display only the most recent 200,000 rows from the filtered data set.
  • For units of measure, including angles, areas, lengths, money, percentages, time (including years, months, weeks, and days), and volume. This applies even if the number is under 10, as in 5 inches.
  • In a group of two or more numbers when at least one of the numbers is 10 or more: The program reports 17 errors, 9 major and 8 minor.
  • To identify an object by number: bits 0 and 1.
  • For decimals: 3.4, 16.7.
  • For fractions in a unit of measure or in a mixed number: (1/2-inch measure, 4 1/2 times as much. – If a number precedes an abbreviation or symbol: 14%, 30+ mpg.
• Don't use abbreviations like K for thousand; or M or MM for million.
• If two numbers are adjacent, spell out one: four 8-character form entries; thirty-two 8-bit bytes.
• To form the plural of a numeral, add s but no apostrophe: Type three 2s.
• When a measurement is used as an adjective, use a hyphen to connect the number to the measurement, as in 10-point type. Otherwise, don't use a hyphen.
• Hyphenate a fraction written as words: Three-fifths, Four and one half.
• Hyphenate a two-element number under 100: Sixty-three, twenty-one.

please

Avoid "please" except when prompting the user to do something inconvenient or when the system is to blame for the situation. 

For example: "The export process can take some time. Please wait until the process completes."

 periods

In headings:

Use a period after a run-in heading (one that begins a paragraph and is immediately followed by text matter on the same line) unless some other mark of punctuation, such as a question mark, is required.

Insuring Your Car. Automobile insurance is actually a package of six different types of coverage. . . .

How Much Will It Cost? How much automobile insurance will cost you depends on your driving record, your age, and how much shopping . . .

Omit the period if the heading is freestanding (displayed on a line by itself). However, retain a question mark or an exclamation point with a freestanding head if the wording requires it.

(Reference: GRM 108)

symbols

Don't pluralize single letters, symbols, or mathematical signs by adding an apostrophe and an s.

• Incorrect: Salesforce replaces unrecognizable characters with @’s.
• Correct: Salesforce replaces unrecognizable characters with the at (@) sign.

When referring to a symbol, spell out the name of the symbol and then enter the symbol in parentheses after it.

• When using an equal (=) sign, add one space on each side.
• Wrap greater-than (>) and less-than (<) signs in parentheses rather than quotation marks.

semicolons

Avoid if possible by rephrasing your content into shorter, simpler sentences. If needed, a semicolon can be used to:  >>> semicolons are fine. 

• Separate coordinate clauses that contain commas
• Separate a lengthy or complex series
• Precede then when used transitionally between clauses of a compound sentence. Avoid these other overly formal conjunctive adjectives: therefore, likewise, consequently, and accordingly.
• Separate clauses of a compound sentence that are very long or are themselves subdivided by commas.
• Separate items in a series that are long and complex.

Place semicolons and colons outside quotation marks and parentheses.

 slashes

• Avoid using slashes (/). In most instances, a slash means or, so use or instead.
• It's acceptable to use slashes in the names of system components, software packages, and so on when appropriate. Also, be especially aware that, in many cases, slashes may be parts of commands or instructions that are essential to perform the task.

spacing

• Insert a space between a number and any multiple-letter abbreviation or unit symbol it modifies: 120 MB
• Omit a space between a number and a single-letter abbreviation or unit symbol: 90%, 401(k)
• When a measurement is used as an adjective, use a hyphen to connect the number to the measurement, as in 10-point type. Otherwise, don't use a hyphen.

sync

Use sync instead of synchronize or synchronization in general use. You can also use resync.

The following terms are related to whether transactions in a group are executed one at a time (synchronous) or at the same or overlapping times (asynchronous). Spell them out:

• asynchronous
• asynchronously
• synchronous

task titles  / how to headings

• Use an imperative verb instead of a gerund for task titles. For example, use “Add Users” instead of “Adding Users” and “Create a Custom Field”, not “Creating Custom Fields”.
• Use a title that describes the customer’s goal, not the UI task, whenever possible. For example, the title “Create a Custom Object” for a task about creating custom objects is better than something more generic.
• Don’t use broad phrases like “Create the Infrastructure to Store Your Data”.
• Don't add an introductory phrase (also known as a stem) to a task or table that appears soon after a topic’s title. For example, a set of steps that immediately follows the title Editing a File does not need the introductory phrase “To edit a file:”. If you include only essential introductory content in a task, you’ll never need a stem.

URLs

Acronym for Uniform Resource Locator (previously Universal Resource Locator). The global address of a website, document, or other resource on the Internet. For example, http://www.goalexandria.com. Acceptable as an acronym by itself. Use a URL, not an URL.

Capitalize the names of websites and web publications. Don’t italicize.

Avoid spelling out URLs, but when you need to, leave off the http://www.

which / that

• Use that to identify a particular item and which to add more detail about something.
• Use that for restrictive or defining clauses: The system administrator accesses the screen that creates reports.
• Use which for nonrestrictive clauses: This screen, which is a new enhancement, reduces duplication of data entry.

who / that

Both that and who can be used to refer to a person, but who is considered more polite: The user who logs in first can access the new feature.