CITES Documentation Style Guide

This is an index of style conventions used in CITES web pages. To ensure consistency of spelling, usage, capitalization, and formatting across the CITES web site, CITES web developers and content providers should adhere to the styles used here.

References

Merriam-Webster's Collegiate Dictionary, 11th ed.

The Chicago Manual of Style, 15 ed.

A Dictionary of Modern American Usage, by Bryan Garner

Our site uses cascading style sheet styles. Our cascading style sheet may be viewed, copied, and downloaded from http://www.cites.illinois.edu/css/css.css

For the proper names of CITES Services, see the Index of All Services.

A

abbreviations

Abbreviated units are to be separated from the numeral by a space.

Ex: 256 MB, 1.6 GHz

anti-spam

Hyphenated.

anti-spyware

Hyphenated.

antivirus

One word; no hyphen.

application/program names

Application names are capitalized when they are a product name (e.g., Netscape, Eudora), or when the item is traditionally spelled with a capital letter (e.g., Pine, Elm, Gopher). Use all caps for all acronyms: SSH, HTML.

B

backup (adj. or noun)

One word.

back up (verb)

Two words.

Ex: "Use NetFiles to back up your files. NetFiles is an excellent backup solution."

boldface and italics

Boldface is to be used sparingly for words that are meant to stand out in a quick scan of the text (keywords, etc.). Italic text is used to indicate emphasis within a sentence.

Ex: "In a paragraph, text in italics does not stand out much; it is used to signify a slight emphasis within the context of the sentence. By contrast, a single word in boldface attracts the attention of the reader at first glance, and it is therefore used to highlight words that the reader might be looking for."

A note about tags: <strong> <b> <em> <i>
For most applications, use <strong> for boldface and <em> for italics. Strictly speaking, strength and emphasis could be indicated in a number of ways, not just by boldface and italics. Our style sheet still renders <strong> as boldface and <em> as italics, though, as a nod to the enduring typographical legacy of these font variations in the world of print media.

There may be occasions, however, when legacy style issues might dictate that italics and boldface be used, such as in a bibliography. Because strength and emphasis are not what is really intended, the use of <strong> and <em> would be inappropriate. In such a case, use <b> and <i>.

breadcrumbs (the navigation aids at the top of every page)

Every page should have breadcrumb links.

The breadcrumbs should be formatted with the text_small style from our cascading style sheet.
They should not be boldface or colored.
They are all lowercase, except for acronyms.
They should not have a link to the page on which they appear.
Links should be separated by a greater-than symbol (>) with a space on each side.

Ex: CITES > styleguide
CITES > network > remote access

Breadcrumbs are to provide links to "higher-level" pages with more general information about the topic of the page on which they appear.

They do not have to mirror the directory structure behind the pages.
The link text does not need to match the full titles of the linked pages; a shortened version can be used.
The link text does not have to mirror the file and directory names of the linked pages.

The author can decide which links to include based on what would best serve readers. Rules about breadcrumbs are intentionally flexible to give authors the freedom to best to address the needs of readers.

Care should be taken to ensure that breadcrumbs on collections of related pages are consistent in structure.

C

campuswide

One word, closed up. No hyphen.

capitalization

For capitalization in filenames, see filenames.
For capitalization in titles, see heads.

Official names and titles are capitalized; informal, shortened, or generic terms are not. Acronyms are generally all caps with no periods.

Ex: the Center for Advanced Study, the center
the chair of the department; Philippe Tondeur, chair of the Department of Mathematics; the chair
the College of Law, the law college, the college
the dean of the college; William Schowalter, dean of the College of Engineering; Dean Schowalter; the dean
the Department of Biology, the biology department, the department
the Office of Admissions and Records, OAR, the admissions office, this office
Professor Gail Hawisher; Gail Hawisher, professor of English; the professor
the School of Music, the music school, the school

Exception: Campus units may have their own capitalization conventions, and CITES web pages may on occasion be required to follow these conventions.

Ex: the University of Illinois, the University

The previous examples would indicate that "the University" should be all lowercase. But official campus documents often use the capitalized form, and it is sometimes appropriate for CITES web pages to follow this style convention.

For capitalization after a colon, follow CMS; use a capital only when the colon introduces multiple sentences.

cascading style sheet

The CITES web site uses a cascading style sheet to ensure consistent formatting. The cascading style sheet can be viewed at http://www.cites.illinois.edu/css/css.css

Cat 6, Category 6

Initial cap; space before the numeral.

checkbox

One word.

CITES

The possessive of CITES is never CITES's. Treat "CITES" as an adjective, or use different wording.

Ex: The CITES web site, the history of CITES.

client

Use client to refer to software. To refer to people, use customer or user.

commas

Use a serial comma (before the "and" or "or") in lists.

Ex: A, B, and C.

command line text

Text that is a direct transcript of computer code, input, or output should use Courier New, Courier, or a similar monospaced font.

Our preferred tag is the text_commandline style in the cascading style sheet.

Ex:chgrp sdclar mailing.lists.html

D

data

Treated as a collective or mass noun rather than a plural.

Ex: The data is inconsistent.

dialog box

Note spelling.

disk, disc

A possible rule: magnetic media, disk; optical media, disc.

drop-down menus

See keyboard shortcuts and menu items.

E

email

All lowercase, no hyphen.

email addresses

Use the complete email address as a link, rather than linking from a name, to make the nature of the link explicit and to ensure printer-friendliness.

Ex: Send comments to cites-example@uiuc.edu.

Note: Owing to concerns about spammers' harvesting email addresses from web pages, it is better to use a form instead of an email address to solicit feedback, if possible.

Engineering WorkStations

As shown. Note the capital S.
In addition, note that this capitalization is necessary only in reference to the relevant division of CITES.

F

file server

Two words.

file system

Two words.

filename

One word.

filenames

Because our server uses index.html as its default page, and to avoid confusion, always use .html instead of .htm as the default filename extension.

Please use all-lowercase filenames.

Never use capitalized filename extensions such as .JPG, .HTML. If your image editor capitalizes filename extensions, please correct them manually.

Never use a space in a filename.

FTP

Capitalized acronym, except when used as a command-line command (e.g., ftp ftp.uiuc.edu).

 

G

H

Heads

We have used CSS to tie font styles to normal heading tags. H1 is the main title of the document. For accessibility reasons, we suggest using heading tags instead of font tags for headings. As long as the title of the page uses H1, and the subheadings are used consistently and in ascending sequence, it is not necessary to use them in exact numeric order. Many pages skip straight from H1 to H3 when there are only two or three levels in the document. Which subheadings to use is up to the author's taste and discretion.

For the page title, use title case: Capitalize the first word, the last word, and all words except coordinating conjunctions, articles, and prepositions with less than five letters.

For all other heads on a page, capitalize the first word of the head only.

This Is an H1 Head

This is an H2 head

This is an H3 head

This is an H4 head

This is an H5 head

This is an H6 head

We suggest left-aligning headings and indenting the following text. To indent, use one of the .blockquote styles.

homepage

One word, lowercase.

 

I

i-card

Always lowercase, with a nonbreaking hyphen.

Internet

Always capitalized.

italics

See boldface and italics.

J

K

keyboard shortcuts and menu items

When describing how to do something in an application offering both clickable menus and keyboard shortcuts, we recommend including instructions for both. Drop-down menus are indicated with hyphen and the greater-than sign (->) between menu items.

Keyboard keys are surrounded by angle brackets (< >).

Ex: Delete the file on the remote server first, by selecting it with the mouse, then hitting the <delete> key, or choosing the menu item File -> Delete

In general, boldface anything that is to be clicked on.

Ex: Click on Start -> Control Panel.

See also boldface and italics and command line text.

L

links

Linked text should clearly indicate the destination of the link. Readers should not be surprised by where they end up after clicking on a link. Ideally, the linked text should correspond exactly to the title of the destination page.

In the anchor tags, use relative paths rather than absolute.

Relative: <a href="../passwords/changes.html">
Absolute: <a href="http://www.cites.illinois.edu/passwords/changes.html">

Listserv

Capitalized when referring to the CITES service. Use mailing list to refer to a single list, Listserv to refer to the software or service, and list server to refer to the machine that hosts the list.

login (noun)

Many application interfaces use this word. Follow the usage of the interface in question.

log in (verb)

Two words.

log in to

Three words.

M

menus

See keyboard shortcuts and menu items.

N

navigation

See breadcrumbs.

Network ID

Capitalized. Abbreviated as NetID.

numbers

Spell out one through nine; use numerals for 10 and up.

Exceptions:
Always spell numbers at beginning of sentences.
Always use numerals in percentages (4 percent, not four percent).
If more than one number is used in a sentence, spell them only if all are less than 10. If even one number is more than 10, use numerals for all the numbers in that sentence.
Ranges: use all numerals (1-10, not one through ten).

Ordinals: Follow the same rules as above (third, eighth, 27th, etc.)

O

offline

One word, closed up.

on-site

Two words, hyphenated.
Notable exception: the official title of the CITES OnSite Consulting service.

online

One word, closed up.

P

paragraphs

We prefer that subheadings are left-aligned, and the paragraphs that follow them are indented. Our preferred means of indenting paragraphs is the paragraph style in the cascading style sheet. Further indentation is accomplished with the blockquote tag.

Ex:

Introductory text

H2

text text text

H3

text text text

blockquote

phone numbers

Use parentheses around area codes and toll-free codes, followed by a space.

Ex: (217) 555-1212, (800) 555-1212

Q

quotation marks

We do not use curly quotes ( “ ” ’ ) because they do not always render properly on all browsers. Use straight quotation marks (") for direct quotations. Use single quotes (') only for quotes within quotes.

R

 

S

site licensed

No hyphen.

stand-alone

Hyphenated.

style sheet

See cascading style sheet.

T

tables of contents

For pages that are more than a couple of "screens" in length, we recommend providing readers with a list of links to at least the primary heads on the page.

This is important for accessibility reasons as well. Users who are blind cannot scan the contents of a document; they must start reading at the beginning and hope they find what they are looking for, and so having a table of contents is extremely useful.

On this page, the alphabetic links at the top serve this purpose.

See also links.

text box

Two words.

times

Use numerals and uppercase abbreviations with periods.

Ex: 2:00 P.M., 3:21 A.M.

titles

Use italics for the title of a published book or periodical: Crime and Punishment, The Daily Illini.

Use title case.

title bar text

The title bar text is the text that appears in the top bar of the browser's application window.

Title bar text should be in the following form, using the page's H1 title between the organization identifier and the University identifier:
Ex: CITES :: Page Title Here - U of I

U

University

Capitalized as an adjective.

University of Illinois at Urbana-Champaign

Avoid using the acronym UIUC, especially in formal documents. For the first reference in a document, use the full name of the campus: the University of Illinois at Urbana-Champaign. Acceptable second-reference usages include Illinois, U of I (for in-state and alumni audiences), and the Urbana campus (to distinguish this campus from the Springfield and Chicago campuses).

Note: We do not avoid "UIUC" when it is part of the name of an established CITES service, such as UIUCnet, or in URLs.

Unix

Initial cap. Not all caps; it is not an acronym.

username

One word.

V

videoconferencing

One word.

VoIP, voice over IP

As shown.

W

web

Lowercase. Avoid "WWW."

web page, web site, web space

Two words, lowercase.

X

Y

Z