Style Guide

This writeup describes the "house style" used in iNews/Berkeley Computing and Communications (BC&C). You may find it useful if you are working on other OCIO/IST publications or websites. Please send comments to

Other style guides and references

After this style guide, in order of precedence, see

Berkeley Editorial Style Guide, June, 2003. [PDF]

The Chicago Manual of Style, 14th Edition

Webster's Ninth New Collegiate Dictionary

This writeup describes exceptions to the other guides, and a number of additions having to do with computer terminology and usage.

See older iNews/BC&C articles and back issues of Berkeley Computing and Communications for additional examples of usage. For current computer usage, see the trade press and the native documentation for the computing environments under discussion.

Abbreviations, acronyms

Spell out words (e.g., mathematics, professor) instead of abbreviating. Do not use symbols such as "%" and "&" except in tabular material. See the Berkeley Editorial Style Guide.

Exceptions: units of measure (e.g., KB, MB, bps), campus unit names as shown in the Campus Telephone Directory (e.g., Business & Administrative Services).

Spell out acronyms on first use and append them in parentheses, e.g.,

Workstation Support Services (WSS)

Exception: use the acronym by itself when the acronym is more familiar than the full name (e.g., Fortran, IBM).

Boldface

Use boldface for command names and, generally, to indicate literal text that is to be entered as-is into a computer:

Enter man chmod for a description of the chmod command . . .

Type y in response to the prompt . . .

Exception: use plain text for pathnames, URLs, email addresses, and other pieces of literal text that by their punctuation are clearly distinguishable as computer text:

/usr/lib/aliases.inc

http://www.berkeley.edu/

avante@socrates.berkeley.edu

However, use boldface to set off single-word Unix filenames that are not otherwise distinguishable as computer text.

Avoid starting a sentence with a boldface computer command.

Do not use quotation marks to delimit computer text.

Do not use boldface for emphasis. Use italics instead. Exception: in certain web contexts, boldface may be more effective than italics in making selected words stand out against plain text, so boldface may be useful for emphasis. But avoid boldface for emphasis in print.

Campus buildings

Spell out campus building names in full, including words such as "Hall", "Building", or "Annex":

293 Evans Hall

Avoid constructions such as

293 Evans [avoid]

Room 293 Evans [avoid]

Evans Hall Room 293 [avoid]

Capitalization

See the Word list. For general rules see the Berkeley Editorial Style Guide and other style guides.

For capitalization in titles, iNews/BC&C uses "downstyle", i.e., capitalize the first word and any proper names.

Always capitalize the first word of a sentence, section heading, or title even if the first word is a proper name that is "not supposed" to be capitalized.

"e-Berkeley" becomes "E-Berkeley" and "i-drive" becomes "I-drive" when they begin a sentence, section heading, or title.

iNews/BC&C column names are capitalized, followed by a colon, followed by the title in downstyle caps:

The Web Corner: Photography tips for web developers

The i-drive Files: Share your summer photos on i-drive

Security Spotlight: Windows file and printer sharing as a security vulnerability

CalAgenda Tips: Viewing several agendas together

What's the Policy?: Privacy and confidentiality

In names of software releases, consider words such as "Version" and "Revision" to be part of the proper name:

System 7.5.3 Revision 2

The Version 8.5 release has several improvements . . .

Comma-separated lists

Use the "serial comma", i.e., the comma before the last item in a series:

A, B, or C . . .

Computer command examples and prototypes

Follow the native conventions of the operating system documentation, or use these rules: (1) Use boldface for literal elements to be typed as-is. (2) Use italics for variable elements. (3) Use square brackets [ ] for optional elements. Following is an example Unix command prototype:

cp [-i] [-p] file1 file2

Command examples and prototypes are most clearly presented on a separate, indented line.

For Unix commands, use en dashes (not hyphens) for command-line flags. Check and adjust the spacing between command-line elements to make sure they do not appear to run together.

For examples in which columnar alignment is important, a monospace font such as Courier can be used.

For interactive examples, which mix user input with computer output, use boldface to indicate the user input, and plain text to indicate the computer output.

Computer words

When generic, lowercased words are used in a computer-specific meaning, set them off in an appropriate way, e.g., in boldface, to distinguish them from normal English words:

See man vacation for a description . . .

Dashes, hyphens

See the Chicago Manual and the Berkeley Editorial Style Guide. In HTML documents, indicate em dashes (long dashes) by two hyphens (with spaces before and after):

We will -- just this once -- explain . . .

Use en dashes to form compounds where one of the elements consists of several words:

. . . a Bay Area-wide network

This HTML document uses a hyphen here but, in a printed document, it would be an en dash. Use en dashes also for Unix command-line flags.

On the Macintosh, to typeset the en dash, use the key combination Option-[hyphen]. For the em dash, use Option-Shift-[hyphen].

Contact information

iNews/BC&C uses the following, typical format for contact information:

Contact iNews/BC&C editors, 2195 Hearst Avenue, 642-5205, avante@berkeley.edu.

This is more concise than

Visit the iNews/BC&C editors at 2195 Hearst Avenue, or call 642-5205, or send electronic mail to avante@berkeley.edu.

The elements can be listed in order of importance, e.g., email address first if that is the preferred mode of contact.

Dates, times

See the Berkeley Editorial Style Guide.

Do not spell the day of the month as 1st, 2nd, 3rd, 4th, etc.

Omit the year if it is clear from the context. For example, in a publication dated December 1996, both of the following are clear:

The meeting was held on November 15.

The meeting will be held on January 15.

Email addresses

Email addresses should be fully qualified with domain names:

avante@socrates.berkeley.edu

user@node.subdomain.berkeley.edu

Use plain text for literal elements, italics for variable elements. Here's one exception, where boldface is used for clarity:

Send email to consult at any central system.

Emphasis

Avoid all caps or boldface for emphasis:

Do NOT delete . . . [avoid]

Do not delete . . . [avoid]

YOU WILL LOSE ALL OF YOUR FILES . . . [avoid]

If emphasis is needed, use italics. Exception: in certain web contexts, boldface may be more effective than italics in making selected words stand out against plain text, so boldface may be useful for emphasis. But avoid boldface for emphasis in print.

Gender

See the Berkeley Editorial Style Guide. Avoid constructions such as

he/she [avoid]

s/he [avoid]

(s)he [avoid]

Hypertext links

In the iNews versions of articles, links are indicated in the following, typical way:

See the UC Berkeley Home Page.

See the Technical Account Management website.

See New computing help for students in this issue.

The link (the underscored part) should use the actual title of the work. The URL of the link can be appended in parentheses. See the section URLs. If the text will appear both online and in print (as BC&C does), the URL will be important to readers of the print version.

If the URL has a preferred alias, e.g., wss.berkeley.edu instead of tuna2.berkeley.edu, use the alias. Check with the webmeister of the target site.

Since the link (the underscoring) already delimits and sets off the title, further delimiting is often unnecessary. Avoid, for example, using underscoring and quotes together:

See "New computing help for students" in this issue. [avoid]

The link should be clearly identified, by actual title and URL if necessary, so that the reader can see what it is without having to follow it. Avoid constructions such as the following, where the destination is unclear:

The IST organization supports computing and communication services . . .

Click here for information about IST . . .

Hyphenation of compound adjectives

See the Word list and the Chicago Manual, Table 6.1, pp. 219-231.

Compound adjectives such as high-speed or fixed-length are hyphenated as needed for clarity. Compound adjectives of the form number-unit are always hyphenated:

8-bit byte

28000-bps modem

Italics

Italics are used for general emphasis, for titles of works, for variable elements of computer syntax, and for introducing new terms along with their definitions.

Italics may also be used for entire paragraphs of supplementary text, such as editor's notes.

IST

IST (not IS&T) is the acronym for Information Services and Technology.

KB, MB

KB (kilobyte) usually means 2^10 (1024) bytes.

MB (megabyte) usually means 2^20 (1048576) bytes, which is more than 1000 KB, which is more than 1000000 bytes.

GB (gigabyte) is defined accordingly.

Leave a space between the number and the unit. Do not use "K" by itself. Avoid

800 K [avoid]

800K [avoid]

10MB [avoid]

In some contexts, such as Macintosh Finder widows in the List view, the "800K" notation has become conventional. Follow the convention in these contexts. But in iNews/BC&C body copy, use the "800 KB" notation.

Some units used in networking, such as kbps (kb/s), use "k" in the conventional scientific sense to mean 10^3 (1000) instead of 2^10 (1024). This is indicated by putting the "k" in lower case.

Keyboard, names of keys

The names of keys (or key combinations) for nonprinting characters are treated as proper names:

Command-Shift-3

Command-Option-Escape

Control-C

Delete

Enter

F10

Return

Shift

Tab

Here are some examples in context:

Press the Delete key . . .

Press Command-W (while holding Command press W) . . .

Type a followed by Return . . .

Press the A key . . .

The last example shows that sequences of printing characters are treated as literal text. Use the verb "press" for key combinations and the verb "type" for literal text.

Lead-in sentence to an indented example or list

Here are two different examples of sentences introducing indented material (both are correct):

Type the following command:

ls -a

Type the command

ls -a

In the first example, the lead-in sentence is complete in itself, so it is terminated by a colon.

In the second example, the lead-in sentence continues without a break into the example, so no punctuation is used (and a period is implied at the end).

Punctuate as though the lead-in continued into the example without a line break and indentation. This writeup contains many examples of such lead-ins.

Machine names

Treat machine names as proper names:

The central Unix machines Garnet, Violet, and Socrates . . .

Exception: when the machine name is part of an email address or computer command, write it in lower case:

Send email to consult@socrates.berkeley.edu . . .

Enter the command ftp socrates.berkeley.edu . . .

Menu entries (Windows or Macintosh)

Use the greater-than sign (>), rendered as > in HTML, to indicate a sequence of successive menu choices:

In Photoshop, select Image > Mode > Indexed Color.

Capitalize menu entries as they appear in the software. Use quotes to set them off only if needed for clarity.

Numbers

See the Berkeley Editorial Style Guide.

We differ slightly from that style guide in that we write numbers without commas in scientific and computer contexts:

28800-bps modem

one megabyte (1048576 bytes)

Commas are OK in other contexts such as the following:

There are now more than 40,000 network connections on campus . . .

Numbers with units of measure

Compound adjectives of the form number-unit are always hyphenated:

8-bit byte

28000-bps modem

However, if the unit functions as a noun, there is no hyphen:

The byte size is 8 bits . . .

A modem operating at 28800 bps . . .

Use a space (or hyphen) between the number and unit of measure:

256 KB of RAM

2 GB hard disk

200 mHz CPU

Don't run these together (256KB). Don't use "K" by itself (800K floppy disk); it needs a unit to complete it (800 KB floppy disk).

Paths (Windows or Macintosh)

When describing a path through a series of nested folders, use colons (with spaces before and after) to separate folder names:

the "Apple software : Software for Apple hardware : Printers" folder . . .

Photo credits

Online: Put photo credits either in the caption of the photo, or in italics at the end of the article.

Print: Put photo credits either in the caption of the photo, or at the end of the masthead.

Plurals

See the Berkeley Editorial Style Guide. For acronyms, use the following as models:

PCs

URLs

1990s

BBSes

Apostrophes (') are used only if needed for clarity:

Macintosh IIsi's

Ph.D.'s

Avoid using (s) to indicate an optional plural:

Store the diskette(s) in a safe place . . . [avoid]

The usual plural form already conveys the idea of indefinite number (zero, one, or more):

Store the diskettes in a safe place . . .

Quotation marks

Follow the Chicago Manual.

In some technical contexts, it may be better to modify the Chicago Manual rules as follows. Place end punctuation outside the quotation marks unless it is actually part of the material inside the quotation marks:

. . . a synonym for "bps".

. . . the article "New computing help for students".

. . . and in the box type ".berkeley.edu".

This is more of a "British" usage, and makes the treatment of quotation marks more consistent with that of parentheses and brackets. If the material inside the quotation marks is a complete sentence, of course, then the ending period goes inside. This style is more "logical" in a formal syntactic sense, but if you are more comfortable with the Chicago Manual rules, you can stick with them

Do not use quotes to delimit material that is already delimited in some other way (all caps, underscored hypertext link).

Do not use single quotes interchangeably with double quotes, or single quotes to delimit literal text (as in some early Unix documentation).

Use quotes to set off titles of web pages, menu entries, and dialog-box options as needed for clarity:

See the Software Topics web page . . .

See "For students" for . . .

The UC Berkeley "Computing & Communications" website . . .

The Photoshop "File" menu . . .

Then select File > Save As and type in . . .

Sometimes capitalization by itself is sufficient and the quotes are not needed.

References

Put reference numbers in brackets.

. . . other webloggers who share a common interest [3].

The core of the Semantic Web [11] — Tim Berners-Lee's vision . . .

Release and version numbers

In names of software releases, consider words such as "Version" and "Revision" to be part of the proper name, and capitalize them:

System 7.5.3 Revision 2

The new Version 2 release includes . . .

When abbeviating, use lowercase "v".

CorporateTime Web client (v2.1)

Spacing between words

Use one space (not more) between words and between sentences. Most word processors provide a search function that can be used to search for multiple spaces.

Slash (/)

Avoid the use of the slash (/) in constructions such as

and/or [avoid]

he/she, s/he [avoid]

The construction "and/or" can usually be replaced by "or" alone. In other cases, the slash can often be replaced by "and", "or", or a comma.

The slash is OK, of course, in pathnames, URLs, and other computer usages.

Symbols

Do not use symbols such as "%" and "&" except in tabular material. See the Berkeley Editorial Style Guide.

Exception: campus unit names as shown in the Campus Telephone Directory (e.g., Business & Administrative Services).

Telephone numbers

Spell out the full seven-digit number, giving the area code if the context calls for it:

642-7582

510-642-7582

If the reader can be assumed to be local or to know that the campus area code is "510," then omit the area code. However, avoid leaving out the "64" prefix:

2-7582 [avoid]

Trademarks

It is not necessary (or practical) to acknowledge every trademark that appears in our publications or websites. However, the About BC&C does acknowledge a short list of major trademarks, the ones most commonly used in that publication. (Historically, BSD Unix was developed at UC Berkeley, which put us in the operating-system business. Thus we were legally required to acknowledge that the Unix trademark belonged to someone else.)

URLs

A URL (Uniform Resource Locator) is an "address" of an Internet information resource, which can be used to form a hypertext link to that resource. See the section Hypertext links. Following are some examples of how URLs are treated in print in BC&C:

http://www.berkeley.edu/

http://wss.berkeley.edu/

http:/istpub.berkeley.edu:4201/bcc/about.html

ftp://cornucopia.berkeley.edu/

If the URL is a "directory" type, include the slash at the end; the pointer to "index.html" (or the default index page) is implied.

If the URL has a preferred alias, e.g., wss.berkeley.edu instead of tuna2.berkeley.edu, use the alias. Check with the webmeister of the target site. If you check the site with a browser, you may not see the preferred alias.

Topics

IT Events

Contributor Guidelines

About this style guide

Other style guides and references

Abbreviations, acronyms

Boldface

Campus buildings

Capitalization

Comma-separated lists

Computer command examples and prototypes

Computer words

Dashes, hyphens

Contact information

Dates, times

Email addresses

Emphasis

Gender

Hypertext links

Hyphenation of compound adjectives

Italics

IST

KB, MB

Keyboard, names of keys

Lead-in sentence to an indented example or list

Machine names

Menu entries (Windows or Macintosh)

Numbers

Numbers with units of measure

Paths (Windows or Macintosh)

Photo credits

Plurals

Quotation marks

References

Release and version numbers

Spacing between words

Slash (/)

Symbols

Telephone numbers

Trademarks

URLs