TidBITS Style Guide

TidBITS Style Guide

If you're submitting an article for TidBITS, try to follow these conventions, but don't stress out over it. We base our styles on the Chicago Manual of Style and Apple Computer's style guidelines.

A - D

a lot

In most (but not all) cases, "a lot" is a junk term or a boring superlative. Because we often edit TidBITS closely in order to sHRink its size, "a lot" tends to get edited out, or - in some cases - we substitute a more exciting superlative. Also, writers tend to get in "a lot" ruts, and use the term several times in a short article. Vary your word choice to make for more interesting reading. See also: really and very.

active voice, active tense

When possible, use the active voice. One thing that's cool about TidBITS is that we rarely read like a press release.

When editing, use discretion and judgement so as to not change the author's meaning. If an author sends us an article and says "edit this up and use it as you like," activate heavily. However, for a MailBIT or a re-print, activate lightly, using your judgement.

actually

In most (but not all) cases, "actually" is a junk word. Because we tend to edit TidBITS in order to sHRink its size, "actually" tends to get edited out. For best results, don't use it in the first place. Also, writers tend to get in "actually" ruts and use the term several times in a short article. Vary your word choice to make for more interesting reading.

allows

When referring to software or hardware, don't use "allows"; instead use "enables." (People allow, computers enable.)

although

Preferred over "while" unless you wish to indicate a duration.

Arrow keys

When describing a keyboard shortcut involving an arrow key, do it like this: " Press Command-Down arrow."

commas

Use a series comma.

Yes: The Mac comes with serial, parallel, and ethernet ports.
No: The Mac comes with serial, parallel and ethernet ports.

Using a series comma avoids potential confusion. In the No example above, a novice user might become confused and think that "parallel and ethernet ports" could be one port with two functions.

Put a comma inside quotation marks, unless the clarity of an instruction would be compromised by not doing so.
Yes: I don't think we can put up with any more of these "features," so I plan to launch a protest.
Yes: Type "R9", wait a moment, type "T5", and then press the mouse button for five seconds.

composed vs comprised

Comprised means "to be made up of," so it would be redundant to write, "comprised of". As Glenn notes:

The font set comprises fourteen weights, all of them degrees of bold.
The font set is composed of lead.
Fourteen weights of bold comprise the font set.
The evening consisted of lamb, beef, mutton, and cow.

contact information

Contact information should go at the end of an article (see MailBITS for an example of contact information at the end of a MailBIT). If you are preparing an article, please try to find contact information. Usually, the snail mail address is unnecessary. Email addresses should be given in terms of Internet addresses. Use the following style to give contact information for a company:

Astonishing Software -- 800/833-6687 -- 415/961-4400 -- 415/666-9999 (fax) <info@astonishing.com>

E - H

email address

Enclose all email addresses in brackets, and be sure that all letters are given as lowercase letters, as in <mickeymouse@disney.com>. Use Internet addresses only. See also, contact information.

enables

Preferred over "allows" since someone allows you to something; a program enables you to do something.

ending an article

After an article, there should be one blank line, then the contact information (indented by four or six spaces). Then there's a single blank line, followed by " Information from:" (note the two leading spaces), then no lines, then the info from listings, with no blank lines again. Finally, two blank lines end the article. Here is an example:

Adobe -- 415/961-4400
Ares Software Corporation -- 415/578-9090
Educational Fontware, Inc. -- 800/806-2155 -- 206/842-2155 <davethompson@dbug.org&rt;
Information From:
Getting Started with QuickDraw GX (a pamphlet in the Peirce Print Tools software package)
"Inside QuickDraw GX Fonts," by Erfert Fenton, Oct-94 Macworld, pg. 122. (An excellent article!)
Apple propaganda
Pixar propaganda

See also: contact information, phone number, references, and email address.

I - L

hold

When referring to pressing keys on a keyboard:
No: Hold down the Option key.
Yes: Press Option.

just

In most (but not all) cases, "just" is a junk word. Because TidBITS is often edited closely to sHRink its size, "just" tends to get edited out. For best results, don't use it in the first place. Also, writers tend to get in "just" ruts, and use the term several times in a short article. Try to vary your word choice to make for more interesting reading.

kilobytes

Use the abbreviation K for kilobytes. The "K" goes directly after the number, with no space between the number and the "K," as in "800K floppy disk." Why? We've always done it this way.

lists, bullet

A bulleted list in the setext format consists of two or more entries starting with a bullet (an asterisk is an acceptable substitute, since an asterisk will replace the bullet when converted to setext format). Use bulleted lists unless the list entries are a sequence of steps (bulleted lists look better in setext).

lists, punctuation

TidBITS prefers punctuated lists, such as:

This is the first list item, and it ends with a period.
This is the second list item, and it ends with a period.

megahertz, MHz

Use the abbreviation, "MHz," instead, as in "The processor runs at 60 MHz." Use a space to separate the number from "MHz."

M - P

numbers

Spell out numbers from zero to ten unless they occur within a technical specification. Use digits for numbers higher than ten.

Yes: 4 dpi, 8 MB, 2 MHz, 4-bit, 10K.
Yes: four different products, eight days delivery, 11 days until vacation.

Q - T

really

Don't use "really" more than necessary. Most writing is more forceful and convincing without it. If you want to use a superlative, use a different term.

references

Refer to past TidBITS issues in a specific way so the links will work in Web browsers, as in "see TidBITS-256_". Be sure to put a dash between "TidBITS" and the number, and also be sure to put an underscore after the number.

If an article is being referenced in Information from:, do it like this:

InfoWorld -- 28-Nov-94, Vol. 16, #48
If it's in text, it would be something like, "the 28-Nov-94 issue of InfoWorld..."

U - X

very: Don't use "very" more than necessary. Most writing is more forceful and convincing without it. Use a different term or remove it.
Web: World Wide Web is a name and a proper noun, and as a result, we always capitalize "Web," "Web page," and "Web site."
webmaster: Although we always capitalize Web (see above), "webmaster" doesn't seem to fall into the same category. There is only one Web, whereas there are many webmasters in charge of many Web sites (in other words, a webmaster is not in charge of the entire Web).
while: Prefer "although" or "though" unless it indicates a duration. While should only be used to indicate the passage of time, as in "while Apple prepared System 8, Microsoft struggled to push Windows 95 out the door."

Y - Z

Special thanks to digital.forest, our Web and mailing list host.