Technology at Berkeley Site Navigation:
This Style Guide describes the "house style" used in the Berkeley Computing and Communications newsletter. You may find it useful if you are working on other IST publications or websites. Please send comments to IT Communications staff.
After this style guide, in order of precedence, see
For names and titles of campus personnel, organizational units, or buildings, see the printed
Spell out words (e.g., mathematics, professor) instead of abbreviating. Do not use symbols such as "%" and "&" except in tabular material. See the University Relations 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.,
Use boldface for command names and, generally, to indicate literal text that is to be entered as-is into a computer:
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:
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.
Spell out campus building names in full, including words such as "Hall", "Building", or "Annex":
See the Commonly-Used Word List. For general rules see the University Relations Style Guide and other style guides.
For capitalization in titles, 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.
BC&C column names are capitalized, followed by a colon, followed by the title in downstyle caps:
In names of software releases, consider words such as "Version" and "Revision" to be part of the proper name:
Use the "serial comma", i.e., the comma before the last item in a series:
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:
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.
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 the Chicago Manual and the University Relations Style Guide. In HTML documents, indicate em dashes (long dashes) by two hyphens (with spaces before and after):
On the Macintosh, to typeset the en dash, use the key combination Option-[hyphen]. For the em dash, use Option-Shift-[hyphen].
BC&C uses the following, typical format for customer-service contact information:
Contact User & Account Services, 241 Evans Hall, 642-7355, accounts@socrates.berkeley.edu.This is more concise than
Visit User & Account Services at 241 Evans Hall, or call 642-7355, or send electronic mail to accounts@socrates.berkeley.edu.The elements can be listed in order of importance, e.g., email address first if that is the preferred mode of contact.
See the University Relations 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:
Email addresses should be fully qualified with domain names:
Avoid all caps or boldface for emphasis:
See the University Relations Style Guide. Avoid constructions such as
In the HTML version of BC&C, links are indicated in the following, typical way:
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 the Commonly-Used 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:
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 (not IS&T) is the acronym for Information Systems and Technology.
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
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 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.
The names of keys (or key combinations) for nonprinting characters are treated as proper names:
Here are two different examples of sentences introducing indented material (both are correct):
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.
Treat machine names as proper names:
Use the greater-than sign (>), rendered as > in HTML, to indicate a sequence of successive menu choices:
See the University Relations Style Guide.
We differ slightly from that style guide in that we write numbers without commas in scientific and computer contexts:
Compound adjectives of the form number-unit are always hyphenated:
Use a space (or hyphen) between the number and unit of measure:
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 BC&C body copy, use the "800 KB" notation.
When describing a path through a series of nested folders, use colons (with spaces before and after) to separate folder names:
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.See the University Relations Style Guide. For acronyms, use the following as models:
Avoid using (s) to indicate an optional plural:
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:
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:
Put reference numbers in brackets.
In names of software releases, consider words such as "Version" and "Revision" to be part of the proper name, and capitalize them:
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.
Avoid the use of the slash (/) in constructions such as
The slash is OK, of course, in pathnames, URLs, and other computer usages.
Do not use symbols such as "%" and "&" except in tabular material. See the University Relations Style Guide.
Exception: campus unit names as shown in the Campus Telephone Directory (e.g., Business & Administrative Services).
Spell out the full seven-digit number, giving the area code if the context calls for it:
It is not necessary (or practical) to acknowledge every trademark that appears in our publications or websites. However, the About This Publication section of 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.)
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:
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.