Technology Style Guide: Difference between revisions

Revision as of 00:10, 15 May 2026

Information Technology Services (ITS) has a Technology Style Guide to maintain consistency and avoid confusion regarding technology-related terminology.

The Communications Office has a general College Editorial Style Guide regarding formatting of print and online content.

Thanks to Lafayette College ITS for the idea, and their generous permission in allowing us to create a similar guide.

Vocabulary

anti-virus

Always hyphenate.

Make sure to install an anti-virus program on your computer.

colleague

Use colleague in place of coworker or co-worker.

Never share your password with a supervisor or colleague.

e-book

Hyphen, no capitalization unless at the start of a sentence.

Thank goodness I can read War and Peace as an e-book now.

E-books are available in your local library.

eduroam

Always lowercase, even at the start of a sentence.

eduroam stands for education roaming.

email

No hyphen, no capitalization unless at the start of a sentence.

The preferred means of communication is email.

employee

A member of the faculty or staff at the College.

faculty, staff

Use faculty members and staff members to avoid awkward singular constructions. When referring to both faculty and staff members, use "employees."

Gmail

One word, no hyphen, capitalize the first letter.

Gmail is Swarthmore's email service.

Google Workspace

Replaces G Suite and Google Apps. Singular.

Google Workspace is Google's set of office productivity software.

login

One word when describing a component of the interface.

Enter your Swarthmore username and password at the login prompt.

log in

Two words when referring to the action of logging in.

You will be prompted to log in.

log in to

Three words, used for the act of logging in to a service.

To update your contact information, log in to MySwarthmore.

pop-up

Lowercase, with hyphen.

Choose one of the options from the pop-up menu.

single sign-on

Always lowercase, with “sign-on” hyphenated. On first reference, spell out single sign-on with the acronym in parentheses. On second reference, you can use the acronym.

Moodle uses single sign-on (SSO).

SSO

See single sign-on.

Swarthmore credentials

Use Swarthmore credentials when referring to a Swarthmore username and password combination in generally descriptive terms. Use Swarthmore username and password when used in specific help documentation.

Your Swarthmore credentials consist of your Swarthmore username and password.

Swarthmore username

The username part of your Swarthmore credentials. Use Swarthmore username for the first reference, afterwards it is acceptable to refer to the username.

When prompted, enter your Swarthmore username in the form.

Swarthmore password

When used in combination with Swarthmore username use Swarthmore username and password. Use username and password on subsequent references.

Do not enter your Swarthmore password in any suspicious web forms.

Tri-Co

Short version of the Tri-College Consortium consisting of Bryn Mawr, Haverford, Swarthmore. Capitalize both words and use a hyphen. Consider using the full version (Tri-College) on the first use followed by Tri-Co afterwards.

Any employee or student at a Tri-Co school has access to Mathematica.

Tri-College

Refers to the Tri-College Consortium consisting of Bryn Mawr, Haverford, Swarthmore. Capitalize both words and use a hyphen.

Any employee or student at a Tri-College school has access to Mathematica.

two-factor authentication

Lowercase, with hyphen. Do not use variants such as "2-factor authentication" or "multi-factor authentication."

Using two-factor authentication makes web applications more secure.

web

Per Swarthmore College style guide, this is lowercase.

I just spent 5 hours searching the web for style guides.

web page

Per Swarthmore College style guide, use two words, lowercase.

Check out my awesome web page on Geocities.

website

Per Swarthmore College style guide, use one word, lowercase.

Swarthmore's website is a masterpiece.

Wi-Fi

Hyphenated, capitalize the first letter of each term.

After moving to eduroam, access to Wi-Fi is much easier.

Documentation Styling

This section contains information on how to format ITS documentation in the KnowledgeBase (KB) wiki site.

Acronyms

Spell out for first citation and follow with acronym in parentheses. For instance, "Information Technology Services (ITS) uses lots of acronyms. ITS is the top department on campus."

Commas

Use the Oxford (or serial) comma style. This means including a comma before the last item in a list. For instance, "Rachael Ray finds inspiration in cooking, her family, and her dog," as opposed to "Rachael Ray finds inspiration in cooking her family and her dog."

Documentation headings

Use the built-in heading styles for document formatting. Do not modify the heading by changing the text size, setting the text to bold, italics, etc. Start with the H2 heading. The page title is the H1 heading and there should only be a single H1 heading on a page.

Lists

If directions need to happen in sequential order, a numbered list or <ol> is appropriate and often helpful.
If documentation is a list of actions or items but do not require a particular order of operations, a bulleted or unordered list or <ul> is appropriate and often helpful.
Generally, one item does not make a list. In other words, do not bullet or number items that do not have another item after them of equal importance.

Spaces between sentences

Use a single space between sentences.

Text formatting

Selection or Option

Use bold to indicate a selection or option. Do not use quotes around the text or change the font.

Examples:

In the Address field ...

Choose My Settings & Devices

Steps in a process

Either use

a numbered or ordered list <ol>
or arrows with spaces between them →

to indicate steps to be followed in order in a process.

Text to Enter

Use bold to indicate the text to enter in a textfield. Do not use quotes around the text or change the font.