Apple | Macintosh PowerBook 190/66 | Technical information | Apple Macintosh PowerBook 190/66 Technical information

K
Apple Publications Style Guide
December 1998
K Apple Computer, Inc.
Copyright © 1998 by Apple Computer, Inc. All rights reserved.
Under the copyright laws, this publication may not be copied, in whole or in part,
without the written consent of Apple.
The Apple logo is a trademark of Apple Computer, Inc., registered in the U.S. and other
countries. Use of the “keyboard” Apple logo (Option-Shift-K) for commercial purposes
without the prior written consent of Apple may constitute trademark infringement and
unfair competition in violation of federal and state laws.
Apple, the Apple logo, AppleCD,
AppleScript, AppleShare, Apple
SuperDrive, AppleTalk, Chicago, eMate,
EtherTalk, HyperCard, LaserWriter,
LocalTalk, Mac, Macintosh, Macintosh
Quadra, MacTerminal, Newton,
Performa, PowerBook, PowerBook Duo,
Power Macintosh, QuickDraw,
QuickTime, StyleWriter, and TrueType
are trademarks of Apple Computer, Inc.,
registered in the U.S. and other
countries.
Balloon Help, Extensions Manager,
Finder, iMac, Macintosh PC Exchange,
and The Apple Store are trademarks of
Apple Computer, Inc.
ii
Adobe and PostScript are trademarks of
Adobe Systems Incorporated.
Helvetica and Times are registered
trademarks of Linotype-Hell AG and/or
its subsidiaries
NuBus is a trademark of Texas
Instruments, Inc.
PowerPC is a trademark of International
Business Machines Corporation, used
under license therefrom.
UNIX is a registered trademark
in the United States and other
countries, licensed exclusively through
X/Open Company, Ltd.
Contents
Figures and tables vi
About This Guide vii
What’s in this guide vii
Conventions used in this guide viii
Style and Usage 1
Appendix A
Technical Notation 105
General considerations 106
Code 106
Syntax descriptions 106
Computer voice in text 107
Metasymbols in text 108
Appendix B
Units of Measure 109
Guidelines 110
iii
Appendix C
How to Write Balloons 115
What Balloon Help can and can’t do 116
General guidelines for writing balloons 117
First describe what the user will accomplish 117
Use the fewest words possible 119
Write separate balloons for checked, selected, or dimmed items 120
Write extra balloons for hidden conditions 122
Don’t name an item unless the name helps the user 123
Don’t name an item that’s already named on the screen 125
Use active voice 126
You can use a sentence fragment beginning with a verb 127
Define unfamiliar words 128
Describe only one way of doing something 129
Go easy on hints 130
Describe only the item the user is pointing to 131
Describe multiple step procedures only if they are simple to remember 132
Guidelines for balloons that will be translated 133
Recommended wording for specific types of balloons 134
Buttons with words 134
Menu titles 135
Menu items 136
Menu items that display dialog boxes 137
Items that aren’t available 137
Radio buttons 138
Checkboxes 139
Groups of buttons or checkboxes 143
Tools in palettes 144
Window parts 145
Dialog box on screen 145
Icons 145
Text entry areas 146
Guidelines for phrasing inside balloons 147
Appendix D
Newton Style Guide 149
Newton terminology 150
Terminology not to use 156
Keep your manual short 157
iv
Appendix E
How to Write a Glossary 159
Audience considerations 160
Know your audience 160
Make definitions explanatory as well as correct 161
Make the context clear 161
Connect ordinary usage with technical meaning 161
Matters of form 162
Design 162
Format of an entry 162
Alphabetization 162
Parts of speech 162
Pronunciation 162
Cross-references 163
Multiple definitions 164
Independence 164
Assembling the glossary 165
v
Figures and tables
vi
Figure 1
Figure 2
Figure 3
Figure 4
Figure 5
Figure 6
Figure 7
Figure 8
Figure 9
Figure 10
Figure 11
Figure 12
Figure 13
Figure 14
Figure 15
An alert box 3
An arrow pointer 6
Buttons 10
Checkboxes 14
The Command key 17
Crossbar pointers 22
A crosshair pointer 22
A dialog box 27
An I-beam pointer 46
Indicators in a hierarchical menu 49
Miniwindows 66
Pointers 76
Radio buttons 83
A menu and a submenu 91
A tear-off menu 95
Table 1
Table 2
Abbreviations for state and territory names 90
Names and abbreviations for units of measure 111
About This Guide
T
he Apple Publications Style Guide is for writers, editors, proofreaders, and others
who work on Apple manuals, product training programs, and electronic instructional
and reference materials. Outside developers of Apple-related products may also find
some parts of this guide useful.
What’s in this guide
This guide is designed as a random-access reference tool, though some users, such as
editors and proofreaders, may want to familiarize themselves with the entire document.
“Style and Usage” shows how certain terms are used in Apple publications and gives
preferred style (capitalization, spelling, and hyphenation) for those terms. It also gives
general rules of style and usage for Apple publications. Entries are listed in alphabetical
order.
The back matter covers special topics that may be useful to those working on Apple
publications.
m Appendix A, “Technical Notation,” gives special style and usage rules that apply
largely or exclusively to technical manuals. (These rules are also included by topic in
“Style and Usage.”)
m Appendix B, “Units of Measure,” gives preferred style for spelled-out
and abbreviated forms of units of measurement likely to occur in
Apple publications.
m Appendix C, “How to Write Balloons,” provides guidelines for writing
onscreen Balloon Help.
m Appendix D, “Newton Style Guide,” gives special style and usage rules that apply to
documentation for Newton products.
m Appendix E, “How to Write a Glossary,” provides guidelines for preparing glossaries.
vii
Conventions used
in this guide
Except in special cases described in this guide, follow the style and usage rules in
The American Heritage Dictionary, The Chicago Manual of Style, and Words Into
Type. In cases where these reference books give conflicting rules, follow The Chicago
Manual of Style for questions of usage and The American Heritage Dictionary for
questions of spelling.
Because modifiers of two or more words are often hyphenated when they precede a
noun, but not when they follow the verb as a predicate adjective, that distinction is
indicated as follows:
An entry followed by adj. in parentheses gives the form to be used when the adjective
immediately precedes the noun it modifies.
An entry followed by pred. adj. in parentheses gives the form to be used when the
adjective is a predicate adjective.
Example: black-and-white (adj.), black and white (pred. adj.)
If a hyphenated adjective has no pred. adj. entry, hyphenate the adjective wherever it is
in a sentence.
If a term should be italicized in text, the entry for that term explicitly states that the
term should be in italics. An example of the term in italics is also given. If an entry
doesn’t explicitly call for italics, the term is usually not italicized.
viii
Style and Usage
abbreviations and acronyms An acronym is a pronounceable word formed from
the initial letter or letters of major parts of a compound term. An abbreviation is
usually formed in the same way but is not pronounced as a word. Acronyms are
always all caps, regardless of the capitalization style of the spelled-out form.
Abbreviation: bps—for bits per second
Acronym: ROM—for read-only memory
Always spell out an abbreviation or acronym on first occurrence, and define it if its
meaning isn’t self-evident. Consider including acronyms and abbreviations in the
glossary. (In some cases, such as reference manuals that are not likely to be read
sequentially, you may want to repeat the spelled-out form on first occurrence in
each chapter or major section.) Give a pronunciation key for acronyms if the
pronunciation is not self-evident.
SCSI (pronounced “SKUH-zee”)
Don’t use periods except in abbreviations for English (nonmetric) units of
measurement or in the abbreviations U.S., A.M ., and P.M . Don’t add an apostrophe
before the s when forming the plural.
ICs, RAMs, ROMs
For the rules on forming the plural of letters, characters, and symbols, see plurals.
Don’t use the Latin abbreviations e.g., etc., and i.e. Instead, use for example, and
so forth, and that is, or equivalent phrases.
For abbreviations of units of measurement and guidelines for using them, see
Appendix B, “Units of Measure.”
For abbreviations of state names, see Table 1 under the entry state names.
1
able (suffix) When adding -able to a word ending in e, drop the e unless it is
preceded by a soft c or a soft g.
browsable, deletable, sharable, sizable, upgradable
changeable, pronounceable, purgeable
abort Don’t use when you mean cancel. Avoid in user documentation.
Compare cancel; exit; halt; interrupt; stop.
above Don’t use to describe an element that has already occurred in a printed
manual. Use a more specific reference, such as earlier in this chapter. For a chapter
or a section, include the chapter or section title. For a figure or a table, include the
number of the figure or table.
For more information, see “Printing” earlier in this chapter.
For a summary of slot and drive numbers, see Table 1-2 earlier
in this chapter.
You can use above to describe an earlier element or section of an onscreen
document that cannot be paged through (such as a single Web page).
AC
Abbreviation for alternating current.
access Avoid as a verb where possible, especially in user manuals. Even in
technical manuals, consider more precise alternatives (for example, log on to).
accessory Use accessory only for actual accessories such as carrying cases and
mouse pads, not for peripheral devices. Don’t use accessory device. Compare
desk accessory; device.
accessory slot Don’t use; use expansion slot.
ACGI Abbreviation for Asynchronous Common Gateway Interface. Spell out on
first occurrence.
active Use to refer to the application or window currently being used. Preferred
to in front (because a program or window that is in front of other programs or
windows may not actually be active).
active-application icon Use when necessary to name the icon of the Application
menu. Preferable to call out the icon in a figure and explain its function without
naming it.
adapter Not adaptor.
address Can refer either to an Internet address or to the location in the
computer’s memory where a piece of information is stored. OK to use just address
for either, as long as the context is clear. See also e-mail address; Internet
address; memory address, memory location; URL; Web address.
addresses Use this form for Apple addresses:
Department Name
Apple Computer, Inc.
1 Infinite Loop, M/S n-X
Cupertino, CA 95014
2
Style and Usage
Advanced Program-to-Program Communication (APPC)
and hyphenation. Spell out on first occurrence.
Note capitalization
AEIMP Abbreviation for Apple Event Interprocess Messaging Protocol. Spell out on
first occurrence.
affect (v.), effect (n., v.)
Affect (v.): The change in format affects [influences] only the text
you’ve selected.
Effect (n.): x-H has no effect [result] on any other window.
Effect (v.): x-H effects [brings about] a change.
A5 world Note capitalization. Not identical to A5 register.
afterward Not afterwards.
alert Refers generically to a signal, either visual (an alert box) or auditory (a
beep), that calls the user’s attention to an unusual situation. Don’t use alert
when you can use the more specific alert box.
alert box Refers to a type of dialog box, like the one shown in Figure 1, to which
the user can respond only by clicking a button (such as OK or Cancel) or by
pressing Enter or Return. Compare dialog box.
m Figure 1 An alert box
alert message Refers to a message presented inside an alert box or elsewhere on
the screen. OK in technical manuals; otherwise, use just message.
alias
Lowercase. Use for with alias (not of or to).
The alias for the selected file is in the Apple menu.
You can also use a file alias or a folder alias. In technical documentation, the
object that the alias represents is called its target. In user documentation, the
object is called the original item. Don’t use aliased.
alignment Use instead of justification to refer to the horizontal placement of
lines of text with respect to the left and right edges of the margin. Alignment can
be flush left, flush right, centered, or justified (that is, flush on both the left and
right margins). Compare justification.
all-in-one Always use as an adjective (all-in-one computer). Avoid in user
documentation, even if the term appears in the product’s name or packaging;
instead, describe the features of the product (a computer with a built-in monitor).
Style and Usage
3
allow Avoid using allow when you can restructure a sentence so that the reader
is the subject.
Correct: FileMaker Pro allows you to create a database.
Preferable: With FileMaker Pro you can create a database.
alphabetic Not alphabetical, except when referring specifically to alphabetical
order. (Exception to American Heritage.)
alphabetization Alphabetize letter by letter, not word by word.
program disk
programmer
program selector
alphanumeric One word.
A .M . Note small caps and periods. (Exception to the rule that abbreviations do
not include periods.)
America, American Refers to both North and South America. Don’t use when you
mean United States. See also U.S.
ampersand Use the ampersand character (&) in text only when describing a
command name or other onscreen element that uses the character. In all other
cases (such as when citing a disk or manual title that uses the ampersand
character) use the word and.
and/or Rewrite to avoid this construction.
angle brackets Use angle brackets, not brackets, to describe these symbols:
< >. When you need to distinguish between the opening and closing brackets,
use left angle bracket and right angle bracket. You can also use less-than sign and
greater-than sign for these symbols if appropriate in the context. See also caret;
circumflex.
anonymous FTP Note lowercase a. See also FTP.
ANSI Acronym for American National Standards Institute. Spell out on first
occurrence.
anti (prefix) Close up except before i, a proper noun, or a proper adjective.
(Hyphenate in those cases.)
API Acronym for application programming interface. Spell out on first
occurrence.
apostrophes Use the curly apostrophe except in computer voice. See also
plurals; possessives; quotation marks.
4
Style and Usage
appendix Use appendixes for background information and other supplementary
material that does not contribute directly to the main tasks being taught in the
manual. In user’s manuals, technical information should go in an appendix.
Chapters are numbered; appendixes are lettered.
The first appendix (Appendix A) begins on a right-hand page unless it is preceded
by an appendix part title. Subsequent appendixes can begin on a right-hand or
left-hand page.
An appendix part title may precede the first appendix and includes only the word
Appendixes. It is always on a right-hand page.
When a book has only one appendix, refer to the appendix as Appendix, not
Appendix A. Cross-references to a single appendix should refer to the Appendix.
appendixes Not appendices.
Apple Attachment Unit Interface (AAUI) Note capitalization. Spell out on first
occurrence.
Apple-authorized dealer Note hyphen. Don’t shorten to dealer except in
passages where using the full term becomes cumbersome or overly repetitive.
Apple-authorized service provider Note hyphen. Don’t shorten to service
provider except in passages where using the full term becomes cumbersome or
overly repetitive.
Apple event Two words; note capitalization. Apple event is not trademarked as a
compound. When you are using trademark symbols in a document, use Apple®
event on first use if that is the first occurrence of Apple (other than in the name
Apple Computer). Names of Apple events are caps/lowercase: Open Application
event, Quit Application event, Open Documents event, Print Documents event,
and so on.
Apple Event Interprocess Messaging Protocol (AEIMP) Note capitalization.
Apple FDHD drive Don’t use; use Apple SuperDrive. The original name for the
Apple SuperDrive, which can read high-density disks. FDHD stands for floppy disk,
high density.
Apple Guide Capitalize both words. Apple Guide is the help system technology;
the content provided in Guide databases (such as Macintosh Guide or Mac OS
Guide) is delivered through the Apple Guide technology. Guides for software or
application programs other than the Mac OS may be called <software name>
Guide (for example, Drive Setup Guide).
Apple (ð) menu When referring to the Apple menu, use both the word Apple and
the symbol (ð ) at first reference. Thereafter, it is preferable to use the phrase Apple
menu without the symbol. Don’t use the ð symbol without the word Apple when
referring to the Apple menu.
Apple SuperDrive The product name for Apple’s disk drive that can read
high-density disks. Originally called Apple FDHD drive. See also disk drive;
high-density disk.
Style and Usage
5
applet Can be any small application, but usually a piece of code that is attached
to an HTML document on the World Wide Web.
AppleTalk Refers to an overall network system and any software that supports it,
including the resources you turn on and off in the Chooser. It’s OK to say
AppleTalk network.
In addition to AppleTalk network, the following terms are appropriate uses
of the word AppleTalk: AppleTalk developer, AppleTalk identification number,
AppleTalk network architecture, AppleTalk software, and AppleTalk zone.
Shared devices used over an AppleTalk network, such as an AppleShare file server
or a shared LaserWriter printer, can be called AppleTalk services.
See also Ethernet; EtherTalk; LocalTalk.
application In user manuals, when referring to a single application program, use
application program on first mention; thereafter, it’s OK to use either program or
application.
Application menu Note capitalization. Use this name for the menu at the far right
side of the menu bar, even though the name does not appear in the menu bar. See
also active-application icon.
application programming interface (API) Not application program interface.
Spell out on first occurrence.
application software Not applications software. Use only when referring to
application software in general. Use application or program when referring to a
single program.
Arabic (adj.) Always capitalized when referring to numerals. See also Roman,
roman.
m Figure 2
An arrow pointer
arrow In user manuals, use pointer in general references; use arrow or arrow
pointer when describing the specific type of pointer shown in Figure 2. Cursor may
be appropriate in describing other interfaces and in technical manuals.
The pointer becomes an arrow [or I-beam, or crossbar, and so on ].
arrowhead One word. Don’t use when you mean the tip of the arrow pointer.
arrow keys Use lowercase in general references. Don’t use direction keys.
The name of each arrow key is capitalized.
Use the arrow keys to move the cursor from cell to cell.
Press the Left Arrow key.
ASCII Acronym for American Standard Code for Information Interchange.
Spell out on first occurrence. The acronym is pronounced “ASK-ee.”
assembler Capitalize assembler only when using the full name: the MPW
Assembler, but the assembler. Don’t use assembler when you mean assembly
language.
assembly language (n.), assembly-language (adj.) Not assembler language.
Note hyphenation of adjective.
6
Style and Usage
assembly time (n.), assembly-time (adj.) Note hyphenation of adjective.
assure Don’t use when you mean ensure. Compare ensure, insure.
Asynchronous Common Gateway Interface (ACGI) Spell out on first
occurrence.
Attachment Unit Interface (AUI) Note capitalization. Spell out on first
occurrence.
audio CD Not CD audio disc.
audio input port Lowercase; no hyphen. Not audio-in port or Audio In port. The
port that connects the computer to RCA-type output ports of video or audio
equipment. Compare sound input port.
audio output port Lowercase; no hyphen. Not audio-out port or Audio Out port.
The port that connects the computer to RCA-type input ports of video or audio
equipment. Compare sound output port.
auto-key (adj.) Note hyphenation.
automatic update Use instead of dynamic update, simultaneous update, or live
link when discussing application programs that support the publish and
subscribe feature of System 7.
autoplay, Autoplay The feature is lowercase; the button name is capitalized.
auto-repeat (n., adj.) Note hyphenation.
auxiliary Not auxilliary.
available disk Not mounted disk (in user documentation).
back end (n.), back-end (adj.) Note hyphenation of adjective.
backlit One word.
back panel Two words. Not backpanel.
backside cache A kind of level 2 cache. Backside cache operations are faster than
those of other level 2 caches. Also OK to use backside level 2 cache. See also level
2 cache.
backslash One word.
backspace (n., v., adj.) One word.
Backspace key Note capitalization.
backup (n., adj.), back up (v.) No hyphen.
backward (adv.) Not backwards when referring to direction. But in certain other
contexts, such as putting a garment on backwards, it’s OK to use backwards.
balloon Lowercase when referring to an individual balloon. Not bubble, text
balloon, speech balloon.
Balloon Help Note capitalization.
ball-point pen Note hyphenation.
Style and Usage
7
BASIC Acronym for Beginners All-purpose Symbolic Instruction Code. No
apostrophe in Beginners; lowercase p in purpose. (Exception to the rule that the
second word in a hyphenated compound is capitalized.) Spell out on first
occurrence.
Beginners All-purpose Symbolic Instruction Code (BASIC) No apostrophe in
Beginners; lowercase p in purpose. (Exception to the rule that the second word in a
hyphenated compound is capitalized.) Spell out on first occurrence.
below Don’t use to describe an element that has not yet occurred in a manual. If
necessary, use a more specific reference, such as later in this chapter. For a
chapter or a section, include the chapter or section title. For a figure or a table,
include the number of the figure or table.
For more information, see “Printing” later in this chapter.
For a summary of slot and drive numbers, see Table 3-2 later in
this chapter.
You can use below to describe a later element or section of an onscreen document
that cannot be paged through (such as a single Web page).
bibliography Don’t include a bibliography unless it serves a very specific
purpose. If you have relied on printed sources other than Apple manuals in
writing your manual, you should credit those sources in a bibliography.
If the scope of your manual is limited but you feel that many readers may want to
seek out more information on their own, a bibliography can also be useful. (In a
printer manual, for example, it might be helpful to include some suggestions for
further reading in the field of desktop publishing; such material might best be
handled as a bibliographic section at the end of the relevant chapter, however,
rather than in a full bibliography in the back matter.)
The bibliography always begins on a new page.
bibliography entries In each entry, invert the first author’s name (last name first,
with a comma both before and after the first name or names). Italicize book and
periodical titles. Enclose article titles in quotation marks. Don’t give the name of
the state or country when the place of publication is a well-known city. If you
need to provide a state name, use the correct postal abbreviation, given in Table 2
under the entry state names.
Book:
Norman, Donald A., and David E. Rumelhart.
Explorations in Cognition. San Francisco:
W. H. Freeman, 1975.
Article:
Sculley, John. “Why We Need a Counterbalance.”
Personal Computing, October 1986, 280–283.
For rules on bibliographic citation of other kinds of material, refer to The Chicago
Manual of Style.
bidirectional (adj.) Use to refer to a script system in which text is generally flush
right and most characters are written from right to left, but some text is written
from left to right as well. Arabic and Hebrew are the only bidirectional script
systems in widespread use. Compare mixed-directional.
8
Style and Usage
bit Don’t use when you mean pixel or a dot on the screen.
bitmap (n., v.), bitmapped (adj.), bitmapping (n.) One word in all forms. You can
use either bitmap font or bitmapped font, but be consistent.
bits per second (bps) Spell out on first occurrence.
black-and-white (adj.), black and white (pred. adj.)
She’s writing about the black-and-white monitor.
The image on the screen is black and white.
For screens, monochrome is usually more appropriate because it encompasses
amber and black, green and black, and so on.
blank character Don’t use; use space character.
blinking Use to describe the insertion point. Don’t use flashing for this purpose.
board Don’t use when you mean card. A board is built in; a card can be removed
by the user. Compare card.
boldface Some book designs use boldface for new terms on first occurrence with
definition. If the term is defined in a marginal gloss, boldface the term in the gloss
as well. Use italics, not boldface, for emphasis in manuals, but don’t overdo it!
bomb Don’t use as a verb, but bomb is OK as an adjective, as in the bomb icon.
book designs The designs of Apple’s customer and technical publications are
maintained by design specialists on the art staff of each writing group. Consult
these people for answers to theoretical or practical questions about book design.
bookmark One word.
Boolean (adj.) Note capitalization.
boot Don’t use for start up or switch on in user manuals. In manuals written for
new users, however, you may want to mention the term boot or include it in your
glossary because users may see it elsewhere.
boot disk Don’t use except in technical documents; use startup disk.
bps Abbreviation for bits per second. Spell out on first occurrence.
braces ( { } ) Not curly brackets, but it’s OK to define braces as curly brackets on
first mention. When you need to distinguish between the opening and closing
braces, use left brace and right brace.
brackets ( [ ] ) Not square brackets. But don’t use brackets when you mean
angle brackets (< >). When you need to distinguish between the opening and
closing brackets, use left bracket and right bracket.
bridge Don’t use interchangeably with router. See router.
browsable Not browseable.
browse (v.) It’s OK to use browse as either a transitive verb (browse the Web) or an
intransitive verb (browse through a Web page).
Style and Usage
9
browser, Internet browser, Web browser Lowercase browser. Use to refer to an
application used to gain access to the World Wide Web and other Internet and
intranet services. Don’t use browser to describe a standard file dialog box or a file
selection list. Don’t use HTML viewer.
Browse tool Note capitalization.
build-to-order Not built-to-order. Note hyphens and lowercase. Always use as an
adjective (your build-to-order computer). Don’t abbreviate as BTO.
built-in (adj.), built in (pred. adj.) Hyphenate only before the noun.
The dialog box shows the name of the disk in the built-in drive.
The 3.5-inch disk drive is built in.
The internal modem is built into the computer.
built-in disk drive You can use either built-in disk drive or internal disk drive.
built-in video card In user manuals, use to describe video cards that are installed
at the factory; don’t use on-board video card. OK to use on-board video card in
technical manuals.
bullets Use to refer specifically to the characters used in printed matter to call
out passages of text or listed items. Use dots to describe the characters that
appear when a user types a password in an onscreen dialog box.
bus, buses Note spelling of plural.
m Figure 3
Buttons
button You click an onscreen button; you press a mechanical button. (Figure 3
shows two kinds of onscreen buttons.) Capitalize names of rounded-rectangle
buttons as you would a title.
Click Cancel.
Click the Connect to Network button.
Press the mouse button.
When a button has no label in the interface, capitalize the name if it describes the
function of the button (for example, the Stop button in AppleCD Audio Player). Use
lowercase if the name describes what the button looks like (for example, the
microphone button). See also click.
Button tool Note capitalization.
cable Use cable to describe what physically connects two pieces of hardware.
Don’t use cabling even when you mean cable collectively. Compare cord.
cable extender, cable terminator Use lowercase even when using the full
product name: LocalTalk cable extender, SCSI cable terminator.
cache (n., v.), cached (v.), caching (n., v.) Note spelling. See also backside cache;
level 2 cache; RAM cache.
Calculator The desk accessory. Note capitalization.
calendar Use Arabic calendar to refer to the lunar calendar used in much of the
Arabic world. Don’t use Muslim or Mohammedan calendar. Use Gregorian
calendar to refer to the calendar used in Europe and the United States.
10
Style and Usage
call (a program) Don’t use when you mean load.
callback (n. or adj.) One word, no hyphen.
callouts Use a callout (a short text label with a line that points to part of a figure)
whenever you need to identify something within a figure. Callouts are usually
positioned outside the boundaries of the figure (especially when the figure is a
photograph or a screen shot), and a thin line without an arrowhead, known as a
leader line, connects the callout to what it identifies within the figure.
Use callouts freely when they are really necessary, but keep in mind that too many
callouts can be distracting to the reader. Keep callouts brief, both for clarity and
for an uncluttered look.
Capitalization style for callouts is initial cap only (sentence style). Use a period if a
callout is a complete sentence; no ending punctuation if a callout is not a
complete sentence. It’s OK to have a mixture of complete sentences and phrases in
one illustration.
can, may Use can to express the ability to perform a function. Use may (or
might) to express the possibility of an action or event or to indicate permission
granted by a licensing agreement. Avoid using may to indicate permission
granted by an operating system or program.
Correct: You can select other print options in the Options dialog box.
Correct: If you turn off virtual memory, you may notice a decrease in
performance.
Incorrect: You may choose Save from the File menu.
cancel In technical manuals, an unconditional, permanent halt that carries the
connotation of undoing something. It’s OK to use cancel instead of halt to avoid
awkwardness. In a dialog box in the desktop interface, Cancel (note
capitalization) is a button the user clicks when he or she doesn’t want to proceed
with a particular action. Compare abort; exit; halt; interrupt; stop.
Cancel button Note capitalization.
canceled, canceling Not cancelled, cancelling.
capability If possible, avoid capability when discussing features of software or
hardware; reword in terms of what the user can do with the feature.
capitalization
all caps
THIS LINE IS AN EXAMPLE OF ALL CAPS.
Avoid using all caps for emphasis.
caps/lowercase (title style)
This Line Is an Example of Caps/Lowercase, or Title Style.
Use caps/lowercase (also called title style) for book titles, part titles, chapter
titles, disk titles, titles of major sections of disks, running feet that use
chapter titles, and cross-references to such titles.
Style and Usage
11
In cross-references to a specific appendix or chapter or to the preface,
capitalize the word Appendix, Chapter, or Preface. But when referring to
appendixes, chapters, or prefaces in general, do not capitalize the word
appendix, chapter, or preface.
See the Preface for more information.
See the Appendix for a list of specifications.
The preface of a manual is a good place to explain the typographic
conventions you follow in the text.
In cross-references to sections that never take a title (glossary, index, table of
contents, and so on), don’t capitalize the name of the section.
Follow these rules when using caps/lowercase:
m Capitalize every word except articles, coordinating conjunctions, to in
infinitives, and prepositions of three letters or fewer (except when a
preposition is part of a verb phrase).
Starting Up the Computer
Introduction to the Macintosh
How to Start Your Printer
Getting Started With Your PowerBook
m Capitalize the first and last word, no matter what their part of speech.
Of Mice and Men
The Rules We Fail to Live By
m Capitalize the second word in a hyphenated compound.
Correct: High-Level Events, 32-Bit Addressing
Incorrect: High-level Events, 32-bit Addressing
Exceptions: Built-in Disk Drive, E-Mail Address
m Capitalize Is, It, Than, That, and This.
initial cap only (sentence style)
This line is an example of initial cap only, or sentence style.
When using initial cap only (or sentence style), capitalize only the first letter
of the first word, as well as the first letter of any proper nouns and proper
adjectives.
Capitalization in cross-references to section heads should match that in the
section heads. For example, if the section head is caps/lowercase, the crossreference to it should be caps/lowercase.
See also button.
12
Style and Usage
Caps Lock The key. Not Shift lock. Note capitalization.
captions Figure captions and table captions should be initial cap only. In
general, a caption should read like a title. Don’t use a caption to explain a figure at
length; make the explanation part of the regular text preceding the figure.
card Refers to a removable circuit board that is installed in a slot. Compare board.
See also interface card; memory expansion card; peripheral card.
card names Capitalize the word card in a card name only if it is part of the
product name; for example, QuickDraw 3D Accelerator Card. Some cards, such as
the Apple TV and FM Radio Tuner card, are not separate products; the word card is
not part of their name. Don’t capitalize card in these cases. For generic names,
don’t capitalize any part of the card name; for example, internal modem card.
caret Don’t use when you mean circumflex. A caret (^) is used, for example, to
mark a dynamic variable in Pascal; a circumflex (ˆ) is an accent used, for example, in
the French verb être. Compare circumflex.
carriage return (CR) Use only when referring specifically to ASCII character $0D or
its equivalent. Use return character when writing about, for example, searches for
return characters. Use Return key for the key you press. Explain the term carriage
return if your manual’s audience includes first-time computer users.
catalog Refers to a list of all files and folders stored on a volume. Don’t use this
term in user documentation.
cathode-ray tube (CRT) Note hyphenation. Spell out on first occurrence.
Don’t use when you mean monitor or screen.
CD Abbreviation for compact disc. Spell out on first occurrence. CDs is acceptable
as the plural form of CD.
cdev Don’t use in user documentation. Use Control Panel (when discussing
System 6 or earlier versions) or control panel (when discussing System 7).
CD-ROM Abbreviation/acronym for compact disc read-only memory. Note
hyphenation. Don’t use CD-ROM as a noun; it must modify another word, such as
drive. As the plural, don’t use CD-ROMs; instead use CD-ROM discs or CDs. See also
CD-ROM drive.
CD-ROM drive Not CD-ROM player. The speed of a CD-ROM drive is measured in
terms of a standard speed of 150 Kbps. CD-ROM drives transfer data at double
speed, 4x speed, 6x speed, and so on. The adjective form is hyphenated (24x-speed
CD-ROM drive). Don’t leave out the x.
central memory Don’t use; use main memory.
central processing unit (CPU) Spell out on first occurrence. Don’t use when
referring to the whole computer. In manuals written for new users, however, you
may want to mention this (mis)use of CPU because users may see it elsewhere.
Never refer to the central processing unit as the unit. See also main unit.
CGI Abbreviation for Common Gateway Interface. Spell out on first occurrence.
Use CGI scripts as the plural form on first occurrence; thereafter, OK to use CGIs.
Style and Usage
13
chapter Capitalize the word chapter in references to specific chapters.
Chapter 5, “Expanding Your Macintosh”
Chapters 4 and 5
in the next chapter
Use caps/lowercase for chapter titles. (See capitalization for guidelines on using
caps/lowercase.)
chapter tables of contents Use tables of contents before each chapter only in
very long manuals (such as Inside Macintosh) where the main table of contents in
the front matter is unmanageable as a locator for sections throughout the entire
book. If you use chapter tables of contents, use them for every chapter.
The format of the chapter tables of contents is identical to that of the main table of
contents, except that level-one heads replace chapter titles, level-two heads
replace level-one heads, and so on. In a book with chapter tables of contents, it’s a
good idea to eliminate level-four heads from the main table of contents; the reader
will most likely consult the chapter tables of contents to locate topics at that level
of detail.
character Use in reference to what a key on the computer’s keyboard stands for.
Compare symbol.
check Don’t use when you mean the action of clicking a checkbox to select
an option.
m Figure 4
Checkboxes
checkbox Refers to an onscreen box like the ones shown in Figure 4. One word;
lowercase. Not box or ballot box. You click a checkbox to select or deselect an
option; you don’t check or uncheck a checkbox. See also button; radio button.
checkmark Use to refer to the X or check symbol that’s in a checkbox. One word.
checksum One word.
chip Use integrated circuit or silicon chip (with an explanation of the term) on
first occurrence. Don’t use chip when you mean microprocessor (PowerPC
microprocessor, not PowerPC chip).
choose Use choose, not select, for menu commands. In general, the user selects
something (such as a disk icon, a graphic image, or a section of text) and then
chooses a command to act on the selection.
For tear-off menus that become palettes, choose is still appropriate. See
also select.
Correct: Choose Paste from the Edit menu.
Incorrect: Select Paste from the Edit menu.
Incorrect: Choose the icon that represents your document.
Chooser The desk accessory. Note capitalization.
Chooser extension Use to refer to a file of type 'RDEV'—a printer driver, for
example.
14
Style and Usage
circuit board (n.) No hyphen.
circumflex Don’t use when you mean caret. A circumflex (ˆ) is an accent used,
for example, in the French verb être; a caret (^) is used, for example, to mark a
dynamic variable in Pascal. Compare caret.
CISC Acronym for complex instruction set computing. Spell out on first
occurrence.
clean installation Not clean install. Note lowercase. You perform a clean
installation; you don’t do a clean install.
click On first occurrence, describe the action of positioning the pointer on an
object and briefly pressing and releasing the mouse button. (You don’t click the
mouse button, you press and release it.) After that, simply refer to the object to be
clicked.
Icon: Click the disk icon.
Button: Click Cancel.
Checkbox: Click Auto Page Numbering.
Don’t use click on. See also click in.
click and drag Don’t use. You either click or drag.
Correct: Drag the icon to the Trash.
Incorrect: Click and drag the icon to the Trash.
click and hold Don’t use. Click means to press and quickly release the mouse
button. Use press when you mean press and hold down the mouse button. See also
press.
click in You click in a window or region, such as a scroll bar; you click all other
onscreen elements, such as icons, checkboxes, and buttons.
click on Don’t use; use click.
clip art Two words.
Clipboard Note capitalization.
close You close a window or a document. Don’t refer to an icon as a closed
window. See also open.
close box Note lowercase. Not go-away box or save box.
close region Don’t use; use go-away region.
CLUT Acronym for color lookup table. Spell out on first occurrence.
coax Don’t use when you mean coaxial.
Style and Usage
15
code Use computer voice for code.
If the language you’re working with has a standard style of indentation, use it. If it
doesn’t have such a style, develop a logical method of your own and use it
consistently.
WHILE i<63 DO
BEGIN
IF odd(i) THEN z := z*w
ELSE z := y
END
Develop a method of spacing around punctuation and use it consistently. It’s
often best to use “English-style” spacing because it’s easy to remember and stick
with.
(height, width: extended; quo: integer);
PageSize = 1024
code file Two words, except in reference to the Pascal predefined file type
codefile.
code names Use exactly the same form for a product’s code name throughout a
manual. (If the name is sometimes misspelled or otherwise treated inconsistently, a
global search-and-replace is not possible.)
cold start (n., v.), cold-start (adj.) Not coldstart.
colons Avoid using colons in text heads; if it is absolutely necessary to use a
colon in a head, capitalize the first word after the colon.
When possible, a colon in text (including a colon used before lists or steps)
should be preceded by an independent clause (a complete thought, with both
subject and verb). However, don’t add otherwise unnecessary text just to change
a partial sentence into an independent clause. If a list follows a partial thought, no
colon should precede the list.
Correct: Do this: Click the icon.
Incorrect: To turn the option off: Click the icon.
Correct: Your Power Macintosh computer includes these storage
devices:
m an ATA hard disk drive
m an optional Zip drive in the expansion bay
Incorrect: Your Power Macintosh computer includes:
m an ATA hard disk drive
m an optional Zip drive in the expansion bay
Correct: Your Power Macintosh computer includes
m an ATA hard disk drive
m an optional Zip drive in the expansion bay
See also lists.
16
Style and Usage
color lookup table (CLUT) Note lowercase; use one word for lookup. Spell out on
first occurrence.
color picker Avoid naming this feature in user documentation; instead, use a
phrase like “Choose a color in the dialog box that appears.”
color pixels Not colored pixels.
colors Colors include shades of gray, so you can use colors to refer to settings
for both grayscale and color monitors. On first mention of setting colors say, for
example, “You can set the number of colors (or shades of gray) that your monitor
can display.” Thereafter, use colors.
command Use command or menu command in user manuals; don’t use
menu option.
The menu contains a list of commands.
Use the Save command to save any changes to your file.
Use menu item to refer to items in the Apple menu and open programs in the
Application menu. A command is in a menu, not on a menu; a menu contains
commands. See also command names.
Command key Use the appropriate symbol for this key rather than solely the
name Command key in all documentation except developer manuals. In Macintosh
user documentation, use x (Command) key on first mention of the key, and then
use the x key or a specific command such as x -Q. Figure 5 shows the Command
key.
To produce the propeller symbol with Microsoft Word, press Control-Q in the
Chicago font.
m Figure 5 The Command key
Command-key equivalent In user documentation, keyboard shortcut is
preferred. Use Command-key equivalent only if all the combinations referred to use
the Command (x) key. In technical documentation, keyboard equivalent is
preferred.
Style and Usage
17
command names Use caps/lowercase; don’t capitalize command.
the Find command
the By Icon command
Don’t capitalize a command name when used as a normal English verb.
Choose Cut from the Edit menu.
Now cut the selected text from your document.
Some commands have three unspaced periods following the command name in the
menu. Use the periods in any text head made up solely of the command name and
in the corresponding entry in the table of contents; don’t use the periods in
running text or in the index.
For commands or other onscreen elements of two or more words whose names are
initial cap only, use quotation marks.
Click the checkbox labeled “Keep lines together.”
commas Use the serial comma (a comma preceding and or or in a list of three or
more items).
Jon now owns a Macintosh computer, a LaserWriter printer, and an
AppleCD CD-ROM drive.
Common Gateway Interface (CGI) Spell out on first occurrence.
Communication Command Language (CCL) Note capitalization. Spell out on
first occurrence.
communication, communications Use the singular to describe the act of
communicating, the plural to describe the technology.
communications link Don’t use; use network connection.
communications slot Note lowercase. Not communication slot. The abbreviation
is CS, not CS slot.
Company, Co. Spell out or abbreviate according to the particular company’s
preference.
compiler Capitalize compiler only when using the full name: the MPW Compiler,
but the compiler.
compile time (n.), compile-time (adj.) Note hyphenation of adjective.
comprise A whole comprises parts. Parts constitute a whole. Don’t use
is comprised of.
A class comprises students.
Students constitute a class.
18
Style and Usage
computer voice Use computer voice (a fixed-width font, such as Courier) for
what the user types, for program listings, and for small pieces of sample code.
Computer voice may also be used for many computer-language elements, such as
reserved words, literals, variable names, and routine names. For more detailed
guidelines on using computer voice in technical documentation, see “Computer
Voice in Text” in Appendix A.
Don’t use computer voice for names of buttons, bars, menu commands, menu
titles, or other onscreen elements that are caps/lowercase; use regular text font for
this purpose. For such items that are initial cap only, use regular text font in
quotation marks.
Click Cancel.
Choose Page Setup from the File menu.
Click the checkbox labeled “Keep lines together.”
Don’t use computer voice for error messages or system messages. If you quote a
message exactly as it appears on the screen, use regular text font in quotation
marks. If you paraphrase a message, use regular text font without quotation
marks.
In user manuals, don’t use computer voice in part or chapter titles; text heads;
cross-references to parts, chapters, or sections; or entries in the table of
contents. Don’t use computer voice for Internet addresses or the addresses of
sites on the World Wide Web. Avoid using computer voice in callouts, marginal
glosses, and figure captions. It is OK, however, to use computer voice for these
elements in technical documentation.
In user manuals, don’t use computer voice for the names of files, folders, or
directories. In some technical documentation, especially reference books for
languages and development systems, it may be appropriate to use computer voice
for the names of files, directories, volumes, and libraries.
Punctuation following a word or phrase in computer voice is in regular text font,
not in computer voice, unless the punctuation mark is part of the computerlanguage element represented or part of what the user should type. Spaces
immediately preceding or following text in computer voice are in regular text font.
See also apostrophes; quotation marks.
configure In user documentation, avoid configure; use set up if possible.
Style and Usage
19
connector Use the following terminology:
Edge connector: the connector on the edge of a peripheral card; fits into
a slot
Jack: a small, round, 1-pin socket used in audio and video connections
Minicircular connector: an 8-pin connector
Plug: a connector with prongs or pins
Slot: a long, thin socket on the main logic board
Socket: a connector with holes
In user manuals, also describe connectors by their shape and size, by the icon
that appears on the connector, or in another way appropriate to the context. The
user should be able to identify the connector easily even if he or she doesn’t
know the terminology. Avoid 9-pin, 11-pin, 25-pin, and 50-pin (as well as the
corresponding DB-9, DB-11, and so on) to describe connectors, because the
actual number of pins may not be the number in the designation. You may,
however, want to mention these terms in a glossary.
Don’t use male or female to describe types of connectors.
Avoid obscure names such as power input unit in favor of more direct terms, such
as recessed plug. See also port.
connector box, LocalTalk Refers to a small white box with a built-in connector
box cable and a 9-pin or 25-pin plug, used to connect devices to LocalTalk cables.
Not connector, connection box, or drop box.
connector box cable, LocalTalk Refers to the built-in cable on a LocalTalk
connector box. Not connection cable or connection box cable.
constitute Parts constitute a whole. A whole comprises parts.
Students constitute a class.
A class comprises students.
container Avoid in user documentation except when explaining what a folder or
disk is; use folder or disk.
contextual menu A menu that appears when you press the Control key and click
an item on the screen in system software version 8.0 and later. Not pop-up menu. A
contextual menu opens or appears; it doesn’t pop up.
Control The key. Don’t use CTRL, but Ctrl is OK when space constraints don’t
allow use of the full term (as in column heads in tables).
control character (n.), control-character (adj.) Note hyphenation of adjective.
control key Don’t use in a general sense; use modifier key. The name of the
specific key is capitalized: Control key.
20
Style and Usage
controlled, controlling Not controled, controling.
Control Panel Note capitalization. A single desk accessory in system software
earlier than version 7.0.
control panel Lowercase. Refers to a file of type 'cdev' that allows the user to
set or control some feature of hardware or software, such as the volume of the
speaker or the number of colors displayed on the screen. Such files are available in
System 7 in the Control Panels folder. Refer to a control panel by its name
(capitalized) and add the words control panel (lowercase)—Views control panel,
Map control panel, Memory control panel, Monitors control panel, Sound control
panel, and so on. However, refer to the General Controls control panel as the
General Controls panel. Compare Control Panel.
Control Panels folder Note lowercase folder. In System 7, a folder located in the
System Folder for storing control panels.
Control Strip Note capitalization. Each part of the Control Strip is a portion (not a
module): the Battery Monitor portion of the Control Strip. Portion names are
capitalized (the Screen Resolution portion).
coprocessor No hyphen.
copy Don’t capitalize unless referring to the Copy command by name. You copy
something using the Copy command; you don’t Copy it. You copy a file onto a disk,
not to a disk.
copy-protect (v.), copy-protected (adj., pred. adj.), copy-protection (n.)
Hyphenated in all forms. A copy-protected disk or file is one that cannot be copied
legally. Compare write-protect, write-protected, write-protection.
copyright page All manuals and updates must have a copyright page or
copyright notice. This page is usually the second in the book and does not have a
page number or a running foot. Onscreen documents also require a copyright
notice.
The copyright page is a boilerplate element; see the boilerplate folder on your
departmental file server to get a disk copy of the appropriate page for your
manual.
All Apple trademarked products mentioned in the manual must receive a credit line
on the copyright page. Certain third-party trademarked products also must
receive a credit line on the copyright page (see the “Special and Licensed
Trademarks and/or Copyrights” section of the most recent Apple trademarks list,
which is available at http://www.apple.com/legal/publictmlist.html). For information
on trademark symbols, see trademarks.
cord Use only to describe a power cord or a phone cord. Compare cable.
Corporation, Corp. Spell out or abbreviate according to the particular
corporation’s preference.
corrupted Avoid if possible. Use damaged instead.
Style and Usage
21
CPU Abbreviation for central processing unit. Spell out and define on first
occurrence. Don’t use when referring to the whole computer. See also main unit.
CR Abbreviation for carriage return. Spell out on first occurrence. Refers to ASCII
character $0D or its equivalent. Use return character when writing about, for
example, searches for return characters. Use Return key for the key you press.
Explain the term carriage return if your manual’s audience includes first-time
computer users.
crash Avoid in user documentation, or reassure the reader that the term crash
does not imply damage to hardware.
creator types A creator type name should be in computer voice and must consist
of exactly four characters (one of which may be a space) inside straight, single,
computer voice quotation marks; for example, 'A/UX', 'ttxt', 'MPS '.
m Figure 6
Crossbar pointers
crossbar One word. Refers to the pointers shown in Figure 6.
crosshair One word. Refers to a pointer that is always two fine crossed lines (see
Figure 7). Use only when the thickness of the lines does not change.
cross-references
m Figure 7
A crosshair pointer
to chapter titles
Use caps/lowercase and enclose the title, but not the word Chapter or the
chapter number, in quotation marks.
See Chapter 2, “Using MacTerminal.”
Some departments may include page numbers in cross-references to chapter
titles; consult your department’s style guidelines.
See Chapter 3, “Setting Up Your Computer,” on page 24.
to disk or disc titles
Use caps/lowercase and italics; don’t use quotation marks. Don’t capitalize or
italicize the word disk, disc, or CD unless it’s part of the title as it appears on
the label. Don’t italicize generic disk or disc names. Don’t include trademark
symbols.
WebObjects Developer CD
Power Macintosh G3 CD
Rhapsody Drivers disk
Disk Tools disk
software install CD
In onscreen text, you can use quotation marks, not italics.
22
Style and Usage
to printed manual titles
Use caps/lowercase and italics; don’t use quotation marks. Don’t capitalize or
italicize phrases like user’s manual unless they are part of the title as it
appears on the cover of the manual. Don’t include trademark symbols.
See Getting Started With Your Macintosh Quadra 950.
See your Macintosh user’s guide.
In onscreen text, you can use quotation marks, not italics.
When referring to an edition number, use lowercase and spell out both the
ordinal number and edition.
See Technical Introduction to the Macintosh Family, second edition, for
more information.
to section titles
Use caps/lowercase and enclose the title in quotation marks. Some
departments may include page numbers in cross-references to the titles of
sections of printed manuals; consult your department’s style guidelines.
See “Trouble Starting Up” in Chapter 4.
See “Before You Install the Software” on page 16.
to onscreen documents
Use quotation marks for references to onscreen documents. Don’t place
quotation marks around the names of specific Guide databases or Apple Help
books, such as Drive Setup Guide or Keychain Access Help. Do place
quotation marks around the names of sections of Guides or “chapters” of an
Apple Help book (as you would the chapters of a printed book).
See the “Using PC Cards” topic area of Mac OS Guide, available in the
Help menu.
See the section “New Features” in AppleScript Help.
CRT Abbreviation for cathode-ray tube. Spell out on first occurrence. Don’t use
when you mean monitor or screen.
CS Abbreviation for communications slot. Spell out on first occurrence. Don’t use
CS slot.
Ctrl Abbreviation for Control; initial cap only. Use only when space constraints
don’t allow use of the full term (as in column heads in tables); otherwise, use
Control, as in Control key or Control-S.
curly brackets ( { } ) Don’t use; use braces, but it’s OK to define braces on first
mention as curly brackets.
cursor In describing the Macintosh desktop interface, use insertion point or
pointer, depending on the context. Cursor may be appropriate in describing other
interfaces and in technical manuals.
Style and Usage
23
custom installation Not custom install. Note lowercase. You perform a custom
installation; you don’t do a custom install.
cut Don’t capitalize unless referring to the Cut command by name. You cut
something using the Cut command; you don’t Cut it.
DAC Acronym for digital-to-analog converter. Spell out on first occurrence.
daisy chain (n.), daisy-chain (v., adj.), daisy-chained (adj., pred. adj.) Hyphenated
except as a noun.
daisy wheel (n.), daisy-wheel (adj.) Note hyphenation of adjective.
dark-on-light (adj.) Note hyphenation.
dashes Use the em dash (—) to set off a word or phrase that interrupts or
changes the direction of a sentence or to set off a lengthy list that would
otherwise make the syntax of a sentence confusing. Don’t overuse em dashes. If
the text being set off does not come at the end of the sentence, use an em dash
both before it and after it.
In cross-references to a specific part of a manual, use an em dash to separate the
part number from the part title.
For more information, see Getting Started With Your Macintosh Quadra
660AV: Part I—Setting Up Your Computer.
(To generate an em dash, press Option-Shift-hyphen. Close up the em dash with
the word before it and the word after it.)
Use the en dash (–) for the following purposes:
m between numbers that represent the endpoints of a continuous range:
bits 3–17, 1986–1987 (but see exception following this list)
m between the elements of a compound adjective when one of those elements is
itself two words: desktop interface–specific instructions
m between keystroke names in a combination keystroke when at least one of
those names is two words or a hyphenated word: Option–x —Up Arrow,
x—Shift–double-click.
m as a minus sign (except in computer voice, when you use a hyphen): –1,
–65,535
Some programming languages, such as Pascal, use two unspaced periods to
represent a range of numbers in code: 0..15. Use this form for number ranges in
code only. Use the en dash elsewhere.
(To generate an en dash, press Option-hyphen. Close up the en dash with the
word before it and the word after it.)
See also hyphenation.
24
Style and Usage
data Singular or plural, depending on the context. When used as a collective
noun, data takes a singular verb. When the meaning is not collective, use a plural
verb. In user manuals, avoid in favor of information if information makes sense in
the context.
Collective and thus singular: Data is processed by the CPU.
Not collective and thus plural: Selected data are transferred immediately.
Data Access Language Always spell out when using in noun form. The acronym,
DAL, should only be used in adjective form and only after the full name of the
product has been previously stated, preferably in close proximity to the acronym.
DAL data manipulation
DAL error codes
This style is for legal purposes; DAL is another company’s trademarked name.
database (n., adj.) One word. As a noun, database refers to the body of data
manipulated by a database program.
data extension Not database extension. Use to refer to a file of type 'ddev'.
data file Two words, except in reference to the Pascal predefined file type
datafile.
data storage cartridge No hyphens. Use to describe a removable storage device,
such as a SyQuest or Mass Micro cartridge. OK to shorten to cartridge.
data terminal ready (DTR) signal No hyphens.
date/time record Note slash and lowercase.
daughter board Don’t use; use expansion board.
DB-9 connector OK in technical manuals. In user manuals, describe the
connector by its size and shape, icon, or in another way appropriate to the
context (because it may have fewer than nine actual pins). In manuals written for
new users, however, you may want to mention the term DB-9 (DB-11, DB-25,
DB-50) or include it in your glossary because users may see it elsewhere.
D-channel (n., adj.) Note hyphenation.
dealer Not dealership. Use Apple-authorized dealer or authorized Apple dealer.
Don’t shorten to dealer except in passages where using the full term becomes
cumbersome or overly repetitive.
default (n., adj.) Define on first occurrence. In user manuals, you may want to use
preset.
Style and Usage
25
dehighlight, dehighlighted Don’t use. Use deselect as a verb when appropriate;
otherwise reword. Use not highlighted as an adjective.
DEL character Not DELETE character or rubout character. Refers specifically to
ASCII character $7F.
Delete The key; not DEL key. Compare Forward Delete (Fwd Del).
depress Don’t use; use press.
deprotect Don’t use; use remove protection.
deselect (v.) OK to use when you mean cancel a selection. Not uncheck,
unselect, unhighlight, or dehighlight. Compare unselected.
desk accessory In System 7 or later, don’t use to refer to small application
programs in the Apple () menu, such as the Scrapbook.
Incorrect: the Calculator desk accessory
Correct: Alarm Clock, Calculator, Scrapbook
Compare accessory.
desktop (n., adj.) One word, lowercase. Refers to the working area on the screen
when the Finder is active. Use desktop or Finder desktop in user manuals when
discussing activities the user performs or things the user sees on the desktop.
Desktop button Note capitalization. The button in the directory dialog box in
System 7.
Desktop file Note capitalization. Refers to a resource file used by the Finder.
Desktop Folder Note capitalization. A folder name in System 7.
device Use to refer to any piece of hardware that connects directly (or indirectly
through a network) to the computer. Use peripheral device on first mention.
Compare accessory.
device name Two words. Note the treatment of these similar terms: filename,
pathname, user name, volume name.
diacritical mark Not diacritic.
26
Style and Usage
dialog box Refers to a box, like the one in Figure 8, that appears on the screen to
request information. Don’t use just dialog to refer to a dialog box. Name dialog
boxes only if necessary. Naming a dialog box after the command that brings it to
the screen is preferable. (The directory dialog box is an exception, named because
it appears so often and thus needs to be uniquely identified.)
Avoid naming features within dialog boxes if at all possible. Instead, rely on figures
with explanatory callouts about the function of each feature. If you need to name a
feature, give it a generic name (such as text box) and make it as unobtrusive a part
of the explanation as you can.
A dialog box appears, or the application program presents or displays a dialog box.
Compare alert box.
m Figure 8 A dialog box
dialog message Don’t use; use message.
dialup No hyphen.
different from Not different than. Make sure that both elements being
compared are parallel nouns.
Correct: The user interface of the Macintosh is different from that of the
Newton.
Incorrect: The user interface of the Macintosh is different from the
Newton.
differently than Use when comparing two parallel clauses. Don’t use
different than, different from, or differently from for this purpose. But rewrite
whenever possible to set up a construction in which different from is used to
compare two parallel nouns.
Incorrect: She uses the computer differently than him.
Correct: She uses the computer differently than he does.
Preferable: Her use of the computer is different from his.
Style and Usage
27
digital-to-analog converter (DAC) Note lowercase and hyphenation. Spell out on
first occurrence.
DIMM Acronym for Dual Inline Memory Module. Spell out on first occurrence.
dimmed Use dimmed, not hollow or grayed, to describe a shaded icon, menu
command, button, or option in a dialog box. Dimmed options cannot be selected.
Dimmed menu commands cannot be chosen. Dimmed icons can represent disks
whose contents are displayed in a window, disks that have been ejected, or files
or folders in the window of a disk that has been ejected. They can also represent
open programs. You don’t need to say dimmed (unavailable) because a dimmed
object is understood to be unavailable.
DIN Use all caps when referring to a type of connector, as in DIN-8.
DIP Acronym for dual inline package. Spell out on first occurrence. Note that the
term DIP switch has no hyphen.
direct-connect (adj.) Note hyphenation.
direction keys Don’t use; use arrow keys.
directory Refers to a subdivision of a volume available in the hierarchical file
system (HFS). A directory can contain files and other directories. In user
documentation, use folder.
directory dialog box Refers to a dialog box that allows you to open or save a file
or otherwise gain access to the hierarchical file system. (See Figure 12.) Not
standard file dialog box, except in technical documentation. Avoid using this term
if possible; just describe what to do in the directory dialog box. If naming is
necessary, name the dialog box according to the context: Open dialog box, Save
dialog box, Save As dialog box.
28
Style and Usage
directory name Refers to the name that appears above a list (directory) of files in
a dialog box. Don’t use menu title for this purpose.
disabled In user manuals, don’t use when you mean dimmed.
disc Use only when referring to a compact disc, videodisc, optical disc, or other
laser technology discs; otherwise, use disk. In ongoing references to compact
discs, disc is preferable to CD or CD-ROM. See also CD-ROM.
disk Not diskette, flexible disk, floppy, floppy microdiskette, micro disk, micro
diskette, or microfloppydiskette. Not disc except when referring to a compact disc,
videodisc, optical disc, or other laser technology discs. (If the medium is magnetic,
it’s disk.) Use floppy disk to distinguish from hard disks or compact discs; never
use just floppy for this purpose. In user documentation, use disk instead of volume
to refer in general to floppy disks, hard disks, shared disks, and CD-ROM discs.
Use an article when appropriate: the disk; a disk; save on a disk, not save to disk.
Never use as a short form for disk drive. Describe a disk according to the following
criteria (and in this order): storage capacity (in number of bytes), physical size (in
inches or centimeters, but always use decimals rather than fractions), removability
from its drive (removable or fixed), and flexibility of the medium (floppy or hard).
For example, 1.4 MB 3.5-inch removable floppy disk or 2 GB 5.25-inch fixed hard
disk.
Include only as much information as is necessary to avoid confusion in the
context of each description (in many cases, disk, hard disk, or floppy disk is
enough).
disk drive (n., adj.) Don’t use drive when you mean disk. Don’t hyphenate disk
drive when it is used as a compound adjective.
See also drive.
diskette Don’t use; use disk.
Style and Usage
29
disk name Use when referring to the name that appears beneath a disk’s icon in
the desktop interface; don’t use disk title for this purpose.
Disk Operating System (DOS) Spell out and capitalize on first occurrence when
referring to a specific disk operating system, such as DOS 5.0 or MS-DOS; spell out
and lowercase disk operating system in generic references.
DOS is an acronym for Disk Operating System.
DOS 5.0 and Pascal are two disk operating systems.
disk or disc titles Use caps/lowercase and italics for the full title of a disk or disc.
The word disk or CD may not be part of the title; follow the usage on the official
label. The is usually not part of the disk title.
Install Disk 1
Apple Displays Software
Use the Disk Tools disk to start up your computer.
Use lowercase when referring to a disk or disc by less than its full title, or for disks
or discs with “generic” titles.
Insert the system software disc into the CD-ROM drive.
Install the software from the printer software disk.
Use the AppleShare disc to install client software on another computer.
display Display is an acceptable synonym for monitor if the product’s name
includes Display. Use to refer to the built-in PowerBook monitor. Don’t use when
you mean desktop or screen.
Correct: Three options appear on the screen.
Incorrect: Three options appear on the display.
Correct: Use a tilted swivel stand for your monitor.
Correct: Position the PowerBook’s display to avoid glare.
display device Refers to a device connected to the computer that displays text or
graphics. If possible, be more specific: monitor or television set.
display sentence Use a display sentence when the appropriate level of text head
would be too prominent for a particular purpose. (The most frequent use of
display sentences is in troubleshooting sections or chapters; they are also used
for tutorials or sequences that tell the user how to carry out a procedure.)
Don’t overuse display sentences; their impact is diminished when they occur too
often. Don’t use display sentences when regular text (or a less prominent element
such as a list) would be just as effective.
30
Style and Usage
display system Refers to a monitor and the display card (sometimes called a video
card) that supports it.
division sign Not division symbol.
document In user manuals, refers to a file the user creates and can open, edit,
and print. HyperCard documents are called stacks. Compare file.
document window Don’t use; use document or window, not both. In technical
manuals, document window is OK in reference to the predefined window type.
DOS Acronym for Disk Operating System. Spell out on first occurrence. In generic
references, spell out and use lowercase.
dot Use dot, not bit, when describing an individual screen pixel. See also pixel.
dot matrix (n.), dot-matrix (adj.) Note hyphenation of adjective.
The video display is presented in the form of a dot matrix.
The StyleWriter produces dot-matrix output.
dots per inch, dot-per-inch (dpi) Spell out on first occurrence; OK to use dpi
thereafter. If used as an adjective preceding a noun, hyphenate and use dot-perinch.
The printer provides a resolution of 300 dots per inch (dpi); it can be
upgraded to 600 dpi.
The printer provides a 300-dot-per-inch (dpi) resolution; some printers
offer 600-dpi resolution.
double click (n.), double-click (v.), double-clicking (n., v.) Note hyphenation.
Small children may have trouble with a double click.
Adults can double-click without difficulty.
Double-clicking allows you to work faster.
You do this by double-clicking the icon.
Down Arrow The key. When referring to more than one of the arrow keys, arrow is
lowercase (as in the arrow keys).
download (v.), downloadable (adj.) One word. A font that can be downloaded is
called a downloadable font, not a downloaded font. (But when a downloadable font
has been downloaded, it’s OK to refer to it as a downloaded font.)
Style and Usage
31
dpi
Abbreviation for dots per inch. Spell out on first occurrence.
drag Refers to the act of positioning the pointer, pressing and holding down the
mouse button, moving the mouse, and then releasing the mouse button. Define
on first mention. Always use drag in reference to objects on the screen. Don’t use
drag the mouse. Don’t use click and drag. Don’t use place, put, or move when you
mean drag.
Correct: Drag the icon all over the screen.
Incorrect: Click and drag the icon to the Trash.
Correct: Drag the icon to the Trash.
Incorrect: Put the icon in the Trash.
drag-and-drop (adj.) Note hyphenation and capitalization. Use only as an
adjective (the drag-and-drop feature of the Mac OS). Don’t use as a compound
verb (since the act of dragging an item includes dropping the item in place).
Incorrect: Drag and drop the file onto the printer icon.
Correct: Drag the file onto the printer icon.
DRAM Acronym for dynamic random-access memory. Pronounced “DEE-ram.”
Spell out on first occurrence.
drive A drive holds storage devices (hard disk drive, CD-ROM drive, Zip drive).
Don’t capitalize drive or disk drive except when describing a preprinted disk drive
label on which the term is capitalized, or when using a product name such as
Apple SuperDrive. Don’t use drive when you mean disk. See also CD-ROM drive;
hard disk.
driver Capitalize the word driver in a driver name only if it is part of the product
name; for example, Sound Driver or Disk Driver. When using the term driver
generically, as in print driver, don’t capitalize. In user documentation, avoid using
driver; use software instead (printer software).
drop box When referring to a LocalTalk conector box, don’t use; use connector
box.
dual inline memory module (DIMM) Note capitalization. Spell out on first
occurrence.
dual inline package (DIP) Spell out on first occurrence.
due to Not due to the fact that. A phrase beginning with due to must follow a
linking verb and must function as a subject complement; it cannot function as an
independent prepositional phrase. Use because of with prepositional phrases.
Correct: The interference was due to a faulty cable.
Correct: Your programs will start up faster because of the additional
memory.
duplicate To create a copy of a file by selecting the file on the Finder desktop
and choosing the Duplicate command from the File menu.
32
Style and Usage
DVD
Don’t spell out; DVD doesn’t stand for a specific term.
DVD-Audio, DVD-Video
Note capitalization and hyphens.
DVD-ROM Don’t use DVD-ROM as a noun; it must modify another word, such as
drive. The plural is DVD-ROM discs, not DVD-ROMs.
DVD-ROM drive Not DVD player when referring to a device that reads DVD discs.
dynamic update Don’t use. Use automatic update when discussing application
programs that support the publish and subscribe feature of System 7.
easy installation Not easy install. Note lowercase. You perform an easy
installation; you don’t do an easy install.
EBCDIC Acronym for Extended Binary-Coded Decimal Interchange Code. Spell out
on first occurrence. The acronym is pronounced “EB-si-dik.”
edition Lowercase. Not edition file except where necessary for explanation.
edition numbers When referring in text to an edition number, use lowercase and
spell out both the ordinal number and edition.
Technical Introduction to the Macintosh Family, second edition.
editor Capitalize editor only when using the full name: the MPW Editor, but
the editor.
effect (n., v.), affect (v.)
Effect (n.): x-H has no effect [result] on any other window.
Effect (v.): x-H effects [brings about] a change.
Affect (v.): The change in format affects [influences] only the text
you’ve selected.
e.g. Don’t use; use for example or such as.
8-pin minicircular connector Note hyphenation. Use a numeral (don’t spell out
eight). After first mention, the shorter minicircular connector is fine.
Avoid in user manuals—describe the connector by its size and shape, icon, or in
another way appropriate to the context, because it may have fewer than eight
actual pins. See also connector.
eject (trans. v.) Don’t use as an intransitive verb.
Correct: The disk drive ejects the disk.
Correct: To eject the disk, drag its icon to the Trash.
Incorrect: The disk ejects.
electromagnetic interference (EMI) Spell out on first occurrence.
11-pin connector Note hyphenation. Avoid in user manuals—describe the
connector by its size and shape, icon, or in another way appropriate to the
context, because it may have fewer than 11 actual pins. See also connector.
Style and Usage
33
ellipsis points Some commands have three unspaced periods following the
command name in the menu. Use the periods in any text head made up solely of
the command name and in the corresponding entry in the table of contents; don’t
use the periods in running text or in the index.
When three periods are used to represent material omitted within a quotation, or
text that trails off, the printing convention is to separate the periods with
spaces:
“What a piece of work is man! . . . in apprehension how like a god!”
Be sure to save your document frequently, because if you don’t . . .
When the material preceding ellipsis points is a complete sentence, add a fourth
point as a period, before the ellipsis points and closed up with the last word:
“In the beginning God created the heaven and the earth. . . . And God
said, Let there be light: and there was light.”
Some programming languages, such as Pascal, use two unspaced periods to
represent a range of numbers in code: 0..15. Use this form for number ranges in
code only. Use the en dash elsewhere.
e-mail Note lowercase and hyphen. Don’t use an article with the noun (don’t
use an e-mail, although an e-mail message is OK). Don’t use as a verb. Capitalize
as E-mail, not E-Mail.
Correct: Send an e-mail message to your mother.
Correct: You can contact Apple Computer by e-mail.
Incorrect: Your mother wants you to e-mail her.
e-mail address E-mail addresses use this format:
username@location.subdomain.domain. For instance, the address
mac@worm.apple.com specifies a user named “mac” at the location (sometimes a
physical computer, but not always) “worm” in the “apple” subdomain of the
“com” domain. Use plain text for e-mail addresses in text. Avoid end-of-line breaks
in e-mail addresses; if necessary, set the address on a separate line. Avoid
punctuation immediately before or after e-mail addresses. See also Internet
address.
eMate
Note capitalization.
embed Not imbed.
em dash See dashes.
EMI Abbreviation for electromagnetic interference. Spell out on first occurrence.
enabled Avoid in user documentation. In technical manuals, it’s OK to use
enabled and disabled when describing buttons, menu commands, and the like.
en dash See dashes.
end-of-file (EOF) The character. Note hyphenation. Spell out on first occurrence.
34
Style and Usage
end user (n.), end-user (adj.) Avoid in favor of user; use end user only if necessary
to distinguish between types of users (a network administrator and other users
on the network; a developer and users of his or her product).
energy management software No hyphen.
energy-saving (adj.) Note hyphenation.
ensure, insure Use ensure to mean make sure or guarantee. Use insure to
describe what an insurance company does. Compare assure.
enter Don’t use when you mean type or press, but enter is appropriate when
referring to data. Enter implies typing information and pressing Enter or Return.
You enter data, type words and characters, and press keys. Compare press;
type.
Enter The key. Note capitalization.
entitled Don’t use; use titled, named, or called.
EOF Abbreviation for end-of-file. Spell out on first occurrence.
equal sign Not equal’s sign, equals sign, or equal symbol.
Esc The key. Include the word Escape in parentheses on first occurrence.
First occurrence: Press the Esc (Escape) key.
Thereafter: Press Esc.
When describing escape sequences, don’t use a hyphen between names of keys,
because the keys are pressed and released separately: Esc 4, Esc F.
et al. Don’t use; use and others.
etc. Don’t use; use and so forth or and so on.
Ethernet One word. Note capitalization. No embedded cap. Refers to one type of
cable system used to link computers and peripheral devices in an AppleTalk
network. OK to use Ethernet network or simply Ethernet depending on the
context. See also AppleTalk; EtherTalk; LocalTalk.
EtherTalk Refers to the software that, along with an Ethernet cable system, is
used for one implementation of the AppleTalk network system. Don’t use EtherTalk
when referring to the cable system; use Ethernet. See also AppleTalk; Ethernet;
LocalTalk.
exit You exit from, leave, or quit a program. You never exit a program.
Compare abort; cancel; halt; interrupt; stop.
expansion bay The space inside a computer where hardware modules (such as
floppy disk drives and CD-ROM drives) can be inserted and removed. OK to use
drive bay if the bay in question takes only storage devices.
expansion board Not daughter board or piggyback board.
expansion slot Not peripheral slot or accessory slot. You can also use slot without
the qualifier expansion. Lowercase even in specific references: slot 1, slot 6.
Style and Usage
35
Extended Binary-Coded Decimal Interchange Code (EBCDIC) Note
hyphenation and capitalization. Spell out on first occurrence.
Extensions Manager Note capitalization. Not Extension Manager.
external monitor Use only to refer to monitors connected to portable
computers or computers with a built-in monitor. For modular computers or
unknown configurations, use additional monitor.
F1, F2, F3, . . . Function keys on the Apple Extended Keyboard. Capitalize the F,
and use plain (not italic) style and Arabic numerals. No space between letter and
numeral.
face Don’t use; use font or font family, whichever is appropriate.
fair language Avoid cultural biases and stereotypes, which may offend some
users of Apple products. Be aware of the variety of people who are potential Apple
customers, and write consciously to include them.
Include a variety of ethnic names in examples: not always Jones, Smith, and
Johnson; sometimes Wong, Scharanski, Kawabata, Contreras, Meyer, and so on.
Include both female and male names in examples: not always John, Jim, and Bob;
sometimes Jane and Susan (better yet, sometimes Maria, Carlos, Yoshiko, and so
on). Portray both women and men in a variety of occupations and situations, not
just stereotypic ones.
Avoid using male pronouns generically. Use he or she, or switch to the plural when
he or she is awkward. Sometimes you can use the second person.
Incorrect: A programmer debugs his code . . .
Correct: A programmer debugs his or her code . . .
Preferable: Programmers debug their code . . .
You debug your code . . .
fanfold paper No hyphen.
Fast Ethernet Note capitalization. See also Ethernet.
fax modem card No hyphen or slash.
FDHD drive Don’t use; use Apple SuperDrive or high-density disk drive. See Apple
SuperDrive.
felt-tip pen Note hyphenation. Not felt-tipped pen.
female connector Don’t use; use socket. See also connector.
fewer, less Use fewer for countable items; use less for quantity or bulk.
The fewer devices in your AppleTalk network system, the less cable
you need.
36
Style and Usage
fiber optics (n.), fiber optic (adj.)
optic cable).
The adjective is two words, no hyphen (fiber
Field tool Note capitalization.
50-pin connector Note hyphenation. Avoid in user manuals—describe the
connector by its size and shape, icon, or in another way appropriate to the
context. See also connector.
figure Line art, photographs, and screen shots are all considered figures.
Figures should be used when their presence will enhance the reader’s
understanding or will illustrate a procedure or point that is not evident from the
text alone. Consider your audience when you plan an art program for a manual.
figure caption Most figure captions include both a figure number and a figure
title. Not all figures need captions; you may spoil some of the effect of whimsical
line art, for example, if you belabor the obvious by giving such a figure a number
and title. But anytime you need to refer specifically to a figure, that figure needs a
number and a title.
Unnumbered figures are not included in a list of figures and tables. A figure with a
number must also have a title; a figure with a title generally has a number.
Figure titles should be short and to the point; a line and a half should be
considered the absolute maximum. Avoid changing type styles in figure titles.
Capitalization style for figure titles is initial cap only; there is no ending
punctuation, even if the figure title is a complete sentence. Use articles in captions
whenever appropriate: The Apple menu, not Apple menu; An external CD-ROM drive
connected to a Macintosh, not external CD-ROM drive connected to Macintosh.
All numbered figures should have an in-text reference to point the reader to the
appropriate figure at the appropriate point. Don’t refer to “the illustration below”
or “the illustration above” when page breaks can change in production.
In-text references can follow five styles:
m standing alone as a complete sentence within parentheses: (See Figure A-12.)
m at the end of the text sentence, in parentheses: Choose Calculator from the
Apple menu (see Figure 6-2).
m standing alone as a complete sentence without parentheses: See Figure 5-5.
m standing alone as a sentence fragment within parentheses: the Apple menu
(Figure 3-13) . . .
m part of the main text sentence, without parentheses: The Page Setup dialog
box, shown in Figure 5-20, appears when. . .
You can use any combination of these styles, but be consistent for comparable
purposes.
Style and Usage
37
figure text Use figure text (also known as labels) for any type that accompanies a
figure (usually line art) but is not connected to the figure by a leader line. (Labels
are usually embedded in the figure.) Keep labels brief. Capitalization style is initial
cap only.
file Refers to any entity stored on a disk, regardless of whether the user can
open, edit, or print it. Compare document.
FileMaker, Inc. Note capitalization.
filename One word. In specific references, capitalization should agree with the
directory listing.
Name the file Paperdoc.
This suitcase contains CurrencyConverter.nib, the file that contains the
user interface.
Note the treatment of these similar terms: device name, pathname, user name,
volume name.
file server Two words. In user documentation, use only when you are explaining
what a file server is (a computer that is dedicated to holding files shared by users
on a network). Use shared disk to refer to a file server icon on the desktop. See also
shared disk.
file sharing (n.), file-sharing (adj.) Two words. Note hyphenation of adjective.
File Transfer Protocol (FTP)
See also FTP.
Note capitalization. Spell out on first occurrence.
file types Two words: code file, data file, destination file, DOS file, source file,
text file, work file. But Pascal predefined file types appear as one word: asciifile,
codefile, datafile, sourcefile, textfile.
A file type name should be in computer voice and must consist of exactly four
characters (one of which may be a space) inside straight, single, computer voice
quotation marks; for example, 'TEXT', 'APPL', 'BIN '.
Finder Note capitalization. The Finder is the program that keeps track of your
files and folders and displays the desktop (the working area on the screen with
disk icons, a Trash icon, and so on).
In user manuals, when discussing activities the user performs or things the user
sees on the desktop, use desktop or, if necessary for the sake of identification,
Finder desktop. Avoid using Finder by itself unless you are describing the program.
A user documentation example:
To print from the desktop, first select the documents you want to print.
A technical documentation example:
The Finder recognizes a program by its unique application signature.
first person Don’t use; rewrite in terms of the reader or the product.
5.25 Not 5 1 ⁄4 when referring to 5.25-inch disks.
38
Style and Usage
fixed-width (adj.) Preferred term to describe fonts, such as Courier, in which
each character takes up the same amount of space on the line. Synonymous
with monospaced.
flashing Don’t use to describe the insertion point or the cursor; use blinking for
this purpose.
flatbed scanner Note that flatbed is one word.
flexible disk Don’t use; use disk.
floppy, floppy microdiskette Don’t use; use disk. Use floppy disk to distinguish
from hard disks or compact discs; never use just floppy for this purpose.
flowchart One word. (Exception to American Heritage.)
folder A folder can contain documents, applications, and other folders. In
Macintosh technical documentation, folders are sometimes referred to as
subdirectories.
Capitalize folder names according to how they are named and how they appear on
the screen. If the word folder does not appear in the folder name, do not capitalize
the f.
Communications folder (the word folder doesn’t appear on the screen)
System Folder (the word folder appears on the screen and is capitalized)
folio Page numbers, or folios, appear on all pages except the inside front and
back covers, the title page, the copyright page, part openers, and any blank lefthand pages preceding chapter openers.
In some cases, a manual may require double folios (that is, folios that include both
the chapter number and the page number within the chapter).
following When used in a phrase that introduces a list, following is always an
adjective, not a noun.
Incorrect: To use this application program, you need the following:
Correct: To use this application program, you need the following
equipment:
font (1) For bitmap fonts, a complete set of characters in one typeface (such as
Times or Garamond), size, and style. (2) For outline fonts, a complete set of
characters in one typeface and style. Don’t use face. Compare font family;
typeface.
Font/DA Mover Note capitalization and slash.
font family Use to refer to a complete representation of characters for one
typeface, including all available sizes and styles (for example, Times or Garamond).
A font family may include both bitmap and outline fonts. Compare font; glyph;
typeface.
font size Not type size. When the meaning is clear, it’s OK to use just size.
font style Not typestyle or typeface attribute. Refers to one or more attributes
such as boldface, underline, italic, shadow, and so on. When the meaning is clear,
it’s OK to use just style.
Style and Usage
39
format (n.) Refers to the arrangement and appearance of text, graphics, and
other elements (such as footers) on a page.
format (v.) When referring to disks, format and initialize mean the same thing.
When referring to tapes, use format rather than initialize.
form feed (n.), form-feed (adj.) Note hyphenation of adjective.
Fortran Note capitalization.
Forward Delete (Fwd Del) The key on the Apple Extended Keyboard. Spell out
on first occurrence. Compare Delete.
fractions In nontechnical documentation, spell out fractions whose denominator
is 10 or less in running text (but not in specification lists, technical appendixes, or
tables). Spelled-out fractions are hyphenated: one-tenth, one-fifth, three-fourths.
When expressing a noninteger greater than 1 in fractional form, use a mixed
numeral rather than an improper fraction.
Correct: 11 ⁄6
Correct: 1/6
Incorrect: 7 ⁄6
free
Don’t use to refer to available random-access memory (RAM); use available.
freeze Use to refer to the behavior of a pointer on the screen. Put quotation
marks around freeze on first use. Avoid using as a noun or to refer to something
the computer does; use a phrase such as not responding.
If the pointer “freezes” on the screen, or the computer doesn’t respond
to the mouse or keyboard, follow these instructions.
front, frontmost The active window is the front or frontmost window.
FTP Abbreviation for File Transfer Protocol. Avoid as a verb; use transfer files
instead. The UNIX command ftp is all lowercase. See also anonymous FTP.
Correct: You use FTP software to transfer files from a remote computer to
your hard disk.
Correct: You use the ftp command to transfer files from a remote
computer to your hard disk.
Incorrect: You can FTP files from a remote computer to your hard disk.
full-duplex (adj.) Note hyphenation.
full-height (adj.) Not full-high.
functional-area Apple events Note hyphenation. See also Apple event.
functionality Avoid. Use function, feature, or another appropriate term.
function keys Refers to the keys on the Apple Extended Keyboard labeled F1, F2,
F3, and so on. Note that function is lowercase.
40
Style and Usage
future tense Whenever possible, don’t use. Use present tense. Don’t switch
unnecessarily from present to future tense when present tense is sufficient to
express a sequence of steps or events. Use present tense for conditional
constructions such as those in the following examples:
Correct: If the noWait parameter is true, play from the disk stops
immediately, and program control returns to the caller.
Incorrect: If the noWait parameter is true, play from the disk will stop
immediately, and program control will return to the caller.
Future tense is sometimes appropriate—for example, when a product described is
not yet available but soon will be.
The configuration of the slot connector will change whenever a newer,
more powerful microprocessor is used in the Macintosh family.
Interapplication communication will play an increasingly important role
in system software.
Fwd Del Abbreviation for Forward Delete. Refers to the key on the Apple Extended
Keyboard. Spell out on first occurrence.
GB Abbreviation for gigabyte. Spell out on first occurrence. The adjective form is
not hyphenated (2 GB hard disk). In the noun form, a space separates the numeral
and the abbreviation, and the preposition of is necessary before the unit that the
value quantifies (2 GB of memory).
Gbit Abbreviation for gigabit.
gender stereotypes See fair language.
General Controls panel Note capitalization and spelling. Not General control
panel or General Controls control panel. See also control panel.
glossary The writer and editor determine whether a book needs a glossary.
Select terms for inclusion in the glossary with the most naive user in mind. (It does
no harm to include terms that most readers already know—those readers will
never bother looking the terms up anyway, and you may be helping the least
experienced of your readers immensely.) Terms unfamiliar to most readers should
always be included in the glossary. Such terms should also be defined on first
occurrence.
glyph In discussions of font technology, use when necessary to refer to the
distinct visual representation of a character that a display device, such as a
monitor or printer, can display. In some non-Roman writing systems, several
different glyphs may be used to represent a single character.
go-away box Don’t use; use close box.
go-away region Not close region.
Style and Usage
41
Gopher Note capitalization. Use as an adjective (a Gopher site, a server with
Gopher software). The UNIX command gopher is all lowercase.
Correct: You can use a Gopher site to find files located on computers
throughout the world.
Correct: You can use the gopher command to find files located on
computers throughout the world.
Incorrect: You use a Gopher to find files on remote computers.
graphic (adj.) Not graphical, except in graphical user interface.
Compare graphics.
graphical user interface Note lowercase. Don’t use the acronym GUI. Compare
graphic.
graphics (n., adj.) The noun form usually takes a singular verb.
High-resolution graphics lets you draw with much more detail.
But: Graphics are the responsibility of the artist.
Use graphics (not graphic) as an adjective in relation to the field of graphic art or
graphic design.
The Macintosh offers graphics capabilities that no one would have
thought possible from a personal computer just a few years ago.
gray Not grey.
grayed Don’t use; use dimmed or highlighted in gray, depending on the
context.
grayscale (n. and adj.) One word.
greater-than sign Note hyphenation. Not greater-than symbol. You can also use
right angle bracket if appropriate in the context.
grey Don’t use; use gray.
grounded outlet Not grounding-type outlet.
grow box Don’t use; use size box.
grow region Not size region.
Guide Short for Apple Guide. Both Apple Guide and Guide are capitalized.
Guide menu Not question-mark menu.
half-duplex (adj.) Note hyphenation.
half-height (adj.) Not half-high.
halt Refers to what happens when the operation of a program stops. Compare
abort; cancel; exit; interrupt; stop.
handshake, handshaking One word. See also XON/XOFF.
42
Style and Usage
hang Don’t use as a description of the computer’s behavior in response to a
system error; use a phrase such as not responding.
Correct: If the computer does not respond to input from the keyboard or
mouse, a system error may have occurred.
Incorrect: If the computer hangs, a system error has probably occurred.
“happy Macintosh” Refers to the startup icon. Use quotation marks. Not
happy Mac.
hard disk (n., adj.) Not rigid disk. Use hard disk to refer to a disk and its
contents, and hard disk drive to refer to the mechanism that holds and accesses
the disk.
Correct: Install the administration software on the server’s hard disk.
Correct: You can install a second hard disk drive in the expansion bay.
hard drive Don’t use. Use hard disk drive to refer to the mechanism that holds
and accesses the hard disk.
HD disk Don’t use. Use high-density disk.
heads
See text head.
hexadecimal In user manuals, don’t use hex as a shorthand form. In technical
manuals, hex is OK, but spell out hexadecimal on first occurrence.
hexagonal-head screw Not hex-head screw.
HFS Abbreviation for hierarchical file system. Avoid in user manuals; use Mac OS
Standard format instead.
HFS Plus Note capitalization. Don’t use HFS+. Avoid in user manuals; use Mac
OS Extended format instead.
hierarchical Not hierarchial.
hierarchical file system (HFS) Spell out on first occurrence.
high bit (n.), high-bit (adj.) Not hi bit or hi-bit. High bit is an acceptable short
form for the noun high-order bit.
high-density disk Preferable to HD disk or 1.4 MB floppy disk. Explain on first use
that these disks contain 1.4 MB of storage space. You may also want to point out
that they are stamped with the letters “HD,” which stand for high density, and
that these disks can’t be used in 400K or 800K disk drives. Compare 1.44 MB disk.
highlight (trans. v.) Don’t use in user manuals. In technical documents, don’t use
as an intransitive verb.
Correct: Your application should know what the selection range is and
highlight it properly.
Incorrect: The icon highlights when you click it.
Compare highlighted; highlighting; select.
Style and Usage
43
highlighted (adj.) No hyphen. Not hilighted. Don’t use inverted except in
technical documentation. When explaining highlighting, use “a highlighted icon
changes color” or “a highlighted icon is filled in.”
Correct: When you click the icon, it becomes highlighted.
Incorrect: When you click the icon, it highlights.
Don’t use unhighlighted or dehighlighted for an item that isn’t highlighted; use
not highlighted.
highlighting (n.) No hyphen. Don’t use in user manuals. In technical documents,
don’t use highlight as a noun.
Correct: When displaying a selection range, an application marks it with
highlighting.
high-order bit (n.) Not hi bit or hi-bit. High bit is an acceptable short form.
high resolution (n.), high-resolution (adj.) The short form hi-res (n., adj.) is OK
in some technical manuals or when space constraints don’t allow use of the full
phrase (as in column heads in tables).
Hindi Don’t use when referring to the writing system used to represent Hindi
and several other Asian languages; use Devanagari.
hit (n.) Don’t use to refer to an item found in a search, or to the act of
connecting to a Web page.
Incorrect: This Web site receives many hits per day.
Correct: Many users connect to this Web site each day.
hit (v.)
Don’t use to instruct users to press a key; use press instead.
hollow Don’t use to describe the icon of a window displayed on the desktop;
use dimmed.
Home card Note capitalization.
home page Two words; lowercase. Use to refer to a Web page that serves as the
directory or entry point to a Web site. Don’t use to refer to an entire Web site.
Incorrect: Visit the Apple home page to purchase products.
Correct: The Apple home page has a link to The Apple Store, where you
can purchase Apple products.
Correct: Visit the Apple Web site for more information about Apple
products.
44
Style and Usage
hot link Don’t use to refer to hypertext links in World Wide Web pages; use
hypertext link or just link.
HTML Abbreviation for hypertext markup language. Spell out on first occurrence.
Use all caps when referring to the programming language. Use all lowercase when
part of a URL. A file can be in HTML or an HTML file, but it is not in HTML format
(because HTML is not a format).
Correct: If you know HTML, you can create Web pages.
Correct: You can find the file at the following address:
http://www.books.com/classics.html
HTTP
a URL.
Abbreviation for Hypertext Transfer Protocol. Use all lowercase when part of
humor Humor can enhance material by adding to a reader’s enjoyment and by
helping to lighten the tone. Humor usually works best in examples, where it is less
likely to distract the reader.
Be careful that your humor is in good taste—one reader’s joke can be another
reader’s insult—and keep in mind that humor may not translate well in localized
manuals. See also fair language.
hypertext link See link.
hyphenation In general, hyphenate two words that precede and modify a noun
as a unit. Follow this rule especially when
m confusion might result if the hyphen were omitted, as in parameter-list pointer
or read-only memory
m the second word is a participle, past or present, as in DOS-formatted disk or
free-moving graphics
m the two modifiers are a number or a single letter and a noun or a participle, as
in 32-bit color or D-shaped connector
When using a unit of measure in a compound adjective, hyphenate the compound
(3.5-inch floppy disk). When using a metric unit of measure, including K, KB, MB,
and so on, do not hyphenate (4 GB hard disk).
Hyphenate compounds such as lower-left corner, top-right portion.
Don’t hyphenate disk drive, hard disk, home control, or thermal transfer either as
nouns or as adjectives.
Style and Usage
45
Don’t hyphenate compounds with very or with adverbs that end in -ly.
very good time
recently completed project
In combination keystrokes, use hyphens to signify that the first key or keys
should be held down while the last key is pressed. (Don’t use hyphens if each key
should be pressed and released separately.) Be sure to explain this convention on
first use.
Control-Shift-N
Esc N
When one of the key names in a combination keystroke is itself two words,
however, use an en dash wherever you would normally use a hyphen.
Option–right bracket
Option–x–Up Arrow
Shift–double-click
x–Shift–double-click
See also dashes.
I Don’t use first person; rewrite in terms of the reader or the product.
m Figure 9
An I-beam pointer
I-beam Note capitalization. Refers to the pointer shown in Figure 9.
IC Abbreviation for integrated circuit. Spell out on first occurrence. No
apostrophe for the plural: ICs.
i.e. Don’t use; use that is.
IEEE Abbreviation for Institute of Electrical and Electronics Engineers. Spell out
on first occurrence.
if necessary Avoid in user documentation. Describe the circumstance in which
the action would be necessary.
iMac Note capitalization. Not Macintosh iMac or iMac Macintosh. OK to use
iMac alone, without the following noun computer.
imbed Don’t use; use embed.
Important Use an Important notice to alert the reader to significant potential
trouble spots that do not cause bodily injury, damage, or loss of data. (Those
situations require a Warning notice.)
Use Important notices and other notices sparingly; they lose effectiveness if they
appear too often. Don’t use an Important notice immediately before or after a Note
or Warning notice, or immediately after a text head. See also Note; Warning.
46
Style and Usage
Incorporated, Inc. Spell out or abbreviate according to the particular
corporation’s preference.
index For detailed guidelines on when a manual should have an index and what
it should include, see the indexing guidelines for your department.
indexes Not indices, unless you mean mathematical indices.
This program can be used to generate indexes.
index style For more information about indexing, see department-specific
guidelines.
Choosing entries
m For many books, two levels of entries are enough. Some books may require
three. The number of levels should be agreed upon by the indexer, writer,
and developmental editor before the indexing begins, though the indexer
may suggest changing the number after work begins. A reference book that
has several parallel parts is a likely candidate for three levels of entries
because the subjects of the parts could add a level.
m A main entry shouldn’t have more than five page numbers after it. If there
are more than five page numbers, use subentries.
m Avoid adjectives as main entries with nouns as subentries; usually such
subentries should be separate main entries. For example, synchronous
communication and synchronous modem should each be main entries;
communication and modem should not be subentries of synchronous.
m Wording should be as terse as possible, but it’s OK to use prepositions
and conjunctions such as in, of, and and to make the relationship between
the main entry and subentry clear. Ignore these “small words” when
alphabetizing.
m Use the subentry defined only when there are multiple page numbers for an
entry; if only one page number is given, no subentry is necessary.
m Names of commands, routines, and options should be followed by an
identifier in the index entry, especially when the same word or words have
another meaning; for example, Print command rather than just Print,
@MAX function rather than just @MAX, PL option rather than just PL.
m Avoid using (s) to make a main entry both singular and plural. Subentries
can be worded so that all of them read correctly with one form of the main
entry.
Style and Usage
47
Cross-references
m See also goes immediately after the main entry. Use a period after the main
entry and use semicolons to separate items in a list of cross-references. For
example,
icons 4. See also applications; disks; documents; folders
m You may use a see cross-reference when there is more than one way to
index a topic and the topic has subentries.
USB. See Universal Serial Bus
OK if “Universal
Serial Bus” has
subentries.
expansion connectors. See connectors
OK if “connectors” has
subentries.
If the topic has no subentries, put the page numbers in both places; don’t use
a see cross-reference.
Universal Serial Bus (USB) 26, 111
USB (Universal Serial Bus) 26, 111
Correct forms if there
aren’t subentries.
You may put the full entry both places even when there are subentries, but
you must set a consistent cutoff point for using cross-references instead of
the full entry (when the entry is more than five lines, for example).
m If an index entry is a term not used in the document, always use a see crossreference to refer to the term that is in the document, even when the entry has
no subentries.
booting. See starting up
Correct whether or not
“starting up” has
subentries.
Order of the entries
m Alphabetize letter by letter, not word by word.
m When an entry begins with a numeral, alphabetize it as if the number were
spelled out. When entries that contain numbers are grouped together, put
the entries in numerical order within that group. For example, Apple II
before Apple III, and 6502 before 65816.
m Indexes may begin with a section of nonalphabetic entries. The section
could include symbols, numbers, Greek letters, and so forth. Most entries in
this section should also appear subsequently, alphabetized as if they were
spelled out.
m Separate entries with alphabetic headings: A, B, and so on. A letter for
which there are no entries should be listed after the preceding letter. (If
there are no entries beginning with X, the heading would be W, X—not X, Y.)
48
Style and Usage
Style of entries
m Do not capitalize all entries. Capitalize only those entries that are
capitalized in the text.
m If a term is in computer voice because it’s a literal computer word (code,
routine names, and so forth), it should be in computer voice in the index. If
it’s in computer voice to indicate what the user types, it should be in
regular text font in the index.
m If a term is in italics in text because it’s the name of a metasymbol or the
name of a disk, it should be in italics in the index. (Generally the name of a
manual shouldn’t be indexed, but if it is, it should be in italics.) If a term is
in italics in text for emphasis or because it’s a word used as a word, it
should be in plain style in the index.
Format of entries
m Use two spaces between the entry and the first page number, no
punctuation.
m Use an en dash for a range of pages; repeat the whole number for the
second number in the range: for example, 102–104. For double-numbered
books, use the word to for page ranges: for example, II-3 to II-7.
indicator Refers to the triangular symbol, shown in Figure 10, that indicates an
additional set of choices (usually a submenu) in a menu.
m Figure 10
Indicators in a hierarchical
menu
indicator light Not LED.
information Use instead of data in user manuals if it makes sense in the context.
Indicators
Info window Not Get Info window or Info box.
infrared No hyphen.
in front Use if desired to explain the term active (the active window is in front of
other windows); subsequently, use active. You can also use to describe palettes
and other windows that “float” on top of active windows.
INIT In technical documentation, INIT may be used to refer to files that contain
'INIT' resources and thus start up when the user turns on the computer. Such
files may be, but are not necessarily, of the 'INIT' file type. Compare system
extension.
initialize Don’t use when referring to tapes; use format for this purpose. When
referring to disks, initialize and format mean the same thing.
ink jet printer No hyphen.
inline One word.
in order to Don’t use unless absolutely necessary; use just to.
input (n., adj.) Don’t use as a verb; use enter or type, depending on the context.
input/output (I/O) device Note capitalization and slash. Spell out on first
occurrence.
Style and Usage
49
insertion point Always preceded by an article.
The vertical blinking bar marks the insertion point.
See also cursor; pointer.
inside Not inside of.
install You install items on a disk, not onto the disk.
Installer Always capitalize, whether referring to a specific Installer program or to
Installer programs in general.
insure, ensure Use insure to describe what an insurance company does. Use
ensure to mean make sure or guarantee.
integrated circuit (IC) Spell out on first occurrence.
interapplication communication (IAC) (n.) Note lowercase. Spell out on first
occurrence.
interapplication communications (adj.) Note lowercase.
interface card Refers to a type of peripheral card that implements an interface to
other devices. Where appropriate, be specific: parallel interface card,
serial interface card.
internal disk drive Use either internal disk drive or built-in disk drive to match
the software.
international resources Lowercase. Refers to resources that are used specifically
by the Macintosh script management system, including the International Utilities.
internet Lowercase. Short for internetwork; refers to any large network made up
of a number of smaller networks. Compare Internet.
Internet Note initial cap. Refers to the worldwide network made up of
interconnected networks that use the TCP/IP networking protocol. When used as a
noun, always preceded by the. Don’t use Internet and World Wide Web or Web
interchangeably; the Web is just one part of the Internet. See also internet;
intranet.
Internet address An Internet address can refer to a computer on the Internet, a
file available over the Internet (for example, a Web page), or an account on a
computer connected to the Internet (for example, an e-mail address). An Internet
address includes a suffix indicating the domain to which the address belongs.
Examples of domain suffixes include
.edu—educational organizations
.com—commercial organizations
.mil—military organizations
.org—nonprofit organizations
.uk—networks located in the United Kingdom
Some examples of Internet addresses are
m delicious.apple.com—Refers to the location “delicious” (sometimes a physical
computer, but not always) in the subdomain “apple” in the “com” domain.
50
Style and Usage
m mac@delicious.apple.com—The e-mail address of the user “mac” at the above
location.
m http://www.apple.com/index.html—A uniform resource locator (URL) using the
hypertext transfer protocol (HTTP) to locate the contents of the file
“index.html” in the directory or location “www” in the subdomain “apple” in
the “com” domain. (Other examples of transfer protocols are FTP, Telnet, and
Gopher.)
Follow these guidelines when using Internet addresses:
m Use plain text for Internet addresses, unless indicating something that the
user types.
m It’s OK to give Internet addresses in the middle of text, as long as the following
guidelines are met:
m Avoid breaking Internet addresses; set them on a separate line if necessary.
m Avoid using punctuation immediately before or after an Internet address
(so readers don’t confuse the punctuation with part of the address).
Reword the sentence containing the address, or set the address on a
separate line.
m You may prefer to put addresses at the end of text or on separate lines
whenever possible to avoid difficulty following these guidelines.
m When referring to a Web site or page, use a generic name rather than the
specific title if possible, because Web page titles change frequently.
m If a user can figure out how to get to the specific information needed from the
home page of a whole site, refer to that page rather than to a specific page,
because organization of sites frequently changes.
m Use a slash at the end of a Web address unless the last component of the
address is a specific file name:
http://www.apple.com/
http://www.apple.com/news.html
See also address; e-mail address; URL; Web address.
Internet service provider (ISP) Note capitalization. Spell out on first
occurrence.
interprocess communication (IPC) (n.) Note lowercase.
interrupt Use as a verb when describing what happens at the hardware level
when a running program is stopped. Hardware interrupts a running program; a
user stops a running program. OK to use interrupt as a noun in technical
manuals. Compare abort; cancel; exit; halt; stop.
intranet Don’t capitalize; refers to a private network, usually owned by a
corporation or institution (your company’s intranet).
Style and Usage
51
in-use light Note hyphenation. Use Ready/In Use light to describe the light on a
LaserWriter printer.
inverse, displayed in If you include this term in a user manual, be sure to explain
it on first occurrence. Use light-on-dark or dark-on-light to explain.
inverted Don’t use when you mean highlighted.
invoke (a program) Don’t use; use load or run, whichever is appropriate in
the context.
I/O device Abbreviation for input/output device. Note capitalization and slash.
Spell out on first occurrence.
IrDA Note capitalization. Short for Infrared Data Assocation, which created a
standard for transmitting data.
IRTalk Note capitalization. A standard for transmitting data.
ISDN Abbreviation for Integrated Services Digital Network. Spell out on first
occurrence.
ISP Abbreviation for Internet service provider; not ISP provider. Spell out on first
occurrence.
italics Use italics, not boldface or underlining, for
m references to titles of disks and titles of manuals
m letters as letters, words as words, and phrases as phrases
the i, the o’s
the word boot
the phrase Welcome to Macintosh
But: Type Q, press x-S
m emphasis (but don’t overdo it)
m metasymbols in syntax examples
Read ([file, ] var)
In onscreen text, you can use quotation marks for references to titles of disks and
manuals and for letters as letters, words as words, and phrases as phrases.
Use italics, not quotation marks, after stands for, labeled, named, termed, the term,
and so on, unless the term is a new term to most readers—in which case, some
book designs use boldface. If the term is an onscreen element, however, use plain
text for elements whose names are caps/lowercase, plain text in quotation marks
for elements whose names are initial cap only.
INIT stands for initialize.
A folder named New Folder appears.
Click the checkbox labeled “Keep lines together.”
Use computer voice, not italics, for a letter, word, or phrase you want the user to
type.
52
Style and Usage
jack See connector.
jacket Use to refer to the permanent cover that encases a 5.25-inch floppy disk.
jargon Avoid jargon whenever possible. Define technical terminology on first
occurrence.
justification Don’t use to refer to the alignment of text to the right or left margin;
use alignment. Text that is aligned on both the right and the left margins is
justified. Compare alignment.
K In user documentation, use as the abbreviation for kilobyte. Spell out on first
occurrence. In technical documentation, use KB for the abbreviation of kilobyte.
There is no space between the numeral and the abbreviation: 800K disk drive. Note
that K is the only abbreviation of its type that is closed up with the numeral. For
the abbreviation conventions for the other terms, see GB; Gbit; KB; Kbit, Kbits;
MB; Mbit, Mbits.
In the noun form, the preposition of is necessary before the unit that the value
quantifies: 800K of memory, 512K of RAM.
K may also be used as an abbreviation for the number 1024. Never use K as an
abbreviation for the number 1000.
KB In technical documentation, use as the abbreviation for kilobyte, including
references to disk capacity: 800 KB disk. The adjective form is not hyphenated. Spell
out on first occurrence. In the noun form, the preposition of is necessary before
the unit that the value quantifies: 512 KB of RAM.
Kbit (sing. n., adj.), Kbits (pl. n.) Abbreviations for kilobit and kilobits. Spell out
on first occurrence.
A space separates the numeral and the abbreviation: 256 Kbit device. In the noun
form, the preposition of is necessary before the unit that the value quantifies: 256
Kbits of memory.
Kbps Abbreviation for kilobits per second. Spell out on first occurrence.
Kbyte Don’t use. Use K in user documentation, KB in technical documentation.
key Use to describe something on the keyboard (press the Option key). You don’t
need to say key on the keyboard.
keyboard equivalent Not Command-key equivalent unless all the combinations
referred to use the Command key. In user documentation, use keyboard shortcut.
keyboard icon Not script symbol or script icon. Refers to the small icon associated
with each keyboard layout. These icons are used in the Keyboard menu and the
Keyboard control panel in System 7.
Keyboard menu Not Script menu.
key-down (adj.) Note hyphenation.
keypad One word. Use keypad or numeric keypad, not numeric keyboard.
keypress One word.
Style and Usage
53
keys Use caps/lowercase for names of modifier keys: Option key, Control key, Shift
key. You press a key; you type a character, a word, or a phrase.
In general, don’t use articles in references to keys.
Press Control.
But ease the user into this construction by using the and key the first time you
mention a keystroke.
Press the Control key.
In combination keystrokes, use hyphens to signify that the first key or keys
should be held down while the last key is pressed. (Don’t use a hyphen if each key
should be pressed and released separately.) Be sure to explain this convention on
first use.
Control-Shift-N
Esc N
When one of the key names in a combination keystroke is two words or a
hyphenated word, use en dashes where you would normally use hyphens.
Option–right bracket
Option–x–Up Arrow
x–Shift–double-click
In combination keystrokes, capitalize but do not italicize or use computer voice
for letters used as key names.
x-C
x-X
When a punctuation key is used in a combination keystroke, use lowercase for the
punctuation key name.
x-period
Option-Shift-hyphen
The key names Escape and Forward Delete may be abbreviated thus: Esc and Fwd
Del. Spell them out at the first occurrence. Don’t abbreviate any other key names.
keystroke One word.
key-up (adj.) Note hyphenation.
keyword Refers to a special word that identifies a particular type of statement
or command, such as IF or CATALOG. Follow the capitalization style of the
programming language involved.
54
Style and Usage
k56flex Note spelling and capitalization. A type of modem technology.
kilobit See Kbit, Kbits.
kilobits per second Abbreviated Kbps. Spell out on first occurrence.
kilobyte See K; KB.
labeled, labeling Not labelled, labelling.
labels See figure text.
LAN Abbreviation for local area network. Spell out on first occurrence.
laptop Don’t use to refer to Apple’s portable computers; use portable computer.
laserdisc One word.
LaserWriter Use only as an adjective (not as a noun): LaserWriter printer.
Examples of model names:
LaserWriter 8500
Color LaserWriter 12/40 PS
launch Don’t use when you mean to open a program. Use open.
leave You leave, exit from, or quit a program. You never exit a program. Compare
abort; cancel; halt; interrupt; stop.
Left Arrow The key. When referring to more than one of the arrow keys, arrow is
lowercase (as in the arrow keys).
left-hand Avoid except in reference to left-hand (verso) pages; use just left
whenever possible.
leftmost No hyphen.
left side Not left-hand side.
less, fewer Use less for quantity or bulk; use fewer for countable items.
The fewer devices in your AppleTalk network system, the less cable
you need.
less-than sign Note hyphenation. Not less-than symbol. You can also use left
angle bracket if appropriate in the context.
let Avoid using let when you can restructure the sentence so that the reader is
the subject.
Acceptable: The Sort command lets you sort items in your document.
Preferable: You use the Sort command to sort items in your document.
or
You sort items in your document with the Sort command.
letter-quality printer Note hyphenation.
Style and Usage
55
letters as letters Italicize a letter when it is used as a letter. Use an apostrophe
and an s to form the plural, but don’t italicize the apostrophe or the s. (Exception
to the rule that punctuation is in the same style as the word it follows.)
o’s, p’s, s’s
In onscreen text, you can use quotation marks around letters as letters; avoid
using the plural.
When discussing fonts and character formation, it may be misleading to use italics
for letters as letters—when discussing a particular character in plain style, for
example. In such cases, use quotation marks.
The letter “å” can be converted to “a”.
Don’t italicize a letter when using it as the name of a key.
Press x-Q.
Use computer voice, not italics, for a letter you are instructing the user to type.
Type Z.
level 2 cache Note lowercase. Can be abbreviated as L2 cache if necessary. Don’t
use secondary cache or second-level cache.
light-on-dark (adj.) Note hyphenation.
-like (suffix) Hyphenate any compound adjective ending in -like unless it is
specifically given as one word in American Heritage. (Exception to The Chicago
Manual of Style.)
Courier is a typewriter-like font family.
A scanner allows you to convert photographs to lifelike images on
the screen.
limited warranty Note lowercase.
line Not necessarily the same as statement. One line may contain several
statements, and one statement may extend over several lines.
line breaks Don’t break a line between Part, Chapter, or Appendix and its number
or letter; between Figure or Table and its number; between slot, port, or drive and
its number; or between a product name and its number. Don’t break a line within
an e-mail address or URL.
line feed (n.), line-feed (adj.) Note hyphenation of adjective.
link (n.) In a hypertext document, such as a World Wide Web page, a link is a tag
assigned to text or graphics. A user clicks the link to go to another page or
perform an action. The term hypertext link is an acceptable synonym. Avoid using
follow a link; say click a link instead.
Incorrect: Follow the link to the page of your choice.
Correct: Click a link on the home page to go to another page.
56
Style and Usage
link (v.) OK to use when describing the act of creating a link in a Web page, but
don’t use to describe connecting to a Web page.
Incorrect: Click the map to link to other pages in the site.
Correct: When creating a Web page, be sure to link to other interesting
Web pages.
linker Capitalize linker only when using the full name: the MPW Linker, but
the linker.
lists For functional definitions of design elements, see the appropriate
specifications for the designs used in your department. There are three types of
lists: bulleted, multicolumn, and numbered; sublists may be nested within. Try to
avoid nesting bulleted lists within bulleted lists, numbered lists within numbered
lists; also avoid using combinations of numbered and bulleted lists that contain
more than a few items. In such cases, the hierarchy can easily become confusing.
bulleted list
Use a bulleted list when you want to stress the parallelism of a number of
options, elements, rules, or instructions that need not be presented or
performed in a particular order.
Within a single list, make all bulleted items parallel.
Bulleted lists generally fall into one of the following three categories:
m a regular sentence broken into a list This type of list emphasizes the
parts of a series. The syntax of the sentence is unbroken; there is no colon
after the main clause, and each bulleted item is a sentence fragment with no
closing punctuation.
m a simple list The main clause is an independent clause followed by a colon,
and each bulleted item is a sentence fragment with no closing punctuation.
See also colons.
m a complex list The main clause is followed by a colon, and each bulleted
item is a complete sentence closed with a period.
If a list is preceded by a colon, the sentence before the colon must be a
complete thought (“To set up your computer, follow these steps:” not “To set
up your computer:”). Exception: In an onscreen document, where space is
limited, the main clause does not have to be an independent clause.
Examples of bulleted lists follow:
a regular sentence broken into a list
The System Folder on the startup disk determines
m which fonts you have available
m which desk accessories are in the Apple menu
m which version of the Finder you’re using
Style and Usage
57
a simple list
MacAPPC routines are divided into four categories:
m conversation routines
m control operator routines
m node operator routines
m transaction program routines
a complex list
Follow these guidelines for password systems:
m Allow passwords to contain both alphabetic and numeric characters.
m Allow passwords to be as long as is practical.
m Never display the password on the screen in clear text, not even while
the user is typing it.
m Provide a way for the user to verify the password when it is entered or
changed.
multicolumn list
Use a multicolumn list when you want to present simple data in tabular form
without all the formal parameters of a table. You may use column heads if you
wish. A multicolumn list does not have spanners, row titles, or stubs, and it
does not use horizontal rules, as the table does.
Multicolumn lists do not have numbers or titles. If you need to refer to them in
text anywhere other than the paragraph preceding, you should probably use
a standard table.
Don’t use a multicolumn list for very complex sets of information or for very
lengthy lists of data. The entire list should not exceed one page; for best
results in page layout, it should probably be no more than half a page long.
Example of a multicolumn list
Here are some examples of file types:
'APPL'
'DRVR'
'PICT'
'TEXT'
'pref'
'scri'
58
Style and Usage
Launchable application
Driver
QuickDraw picture
Stream of ASCII characters
Preferences file
System extension for script systems
numbered list
Use a numbered list when you want to stress the sequential nature of steps,
rules, or instructions.
Each item in the list should be a complete sentence. Begin each item with a
capital letter and end each item with closing punctuation.
Example of a numbered list
To erase a disk, follow these steps:
1. Insert the 800K disk you want to erase.
2. Choose Erase Disk from the Special menu.
3. In the next dialog box, type a name for the disk.
4. Choose a format (if a pop-up menu appears next to the word “Format”).
5. Click Erase.
lithium ion A battery technology. No hyphen. Abbreviated Li-ion.
live link Don’t use to refer to hypertext links in World Wide Web pages; use
hypertext link or just link.
lo-bit Don’t use; use low-order bit or low bit as a noun, low-bit as an adjective.
local area network (LAN) Three words; no hyphen. Spell out on first occurrence;
thereafter, OK to use abbreviation.
localizable Don’t use.
Correct: An application that follows the human interface guidelines
should be easy to localize.
Incorrect: An application that follows the human interface guidelines
should be easily localizable.
localize Takes preposition for, not to.
Correct: Whether you localize your application for the French language
or for French Canada, it is essential that you test its interface with
appropriate users.
Incorrect: Whether you localize your application to the French language
or to French Canada, it is essential that you test its interface with
appropriate users.
LocalTalk One word. Note capitalization. Refers to one type of cable system used
to link computers and peripheral devices in an AppleTalk network. OK to use
LocalTalk network or simply LocalTalk depending on the context. See also
AppleTalk; Ethernet; EtherTalk.
LocalTalk cable Not AppleTalk cable. Note lowercase c.
Style and Usage
59
LocalTalk cable extender Not AppleTalk cable extender. Note lowercase c and e.
LocalTalk connector box Not AppleTalk connector, AppleTalk connector box, or
LocalTalk connector. Note lowercase c and b.
LocalTalk PC Card Not AppleTalk PC Card.
LocalTalk plug Don’t use; use the appropriate connector name, such as 9-pin
connector or 8-pin minicircular connector. See also connector.
LocalTalk port Don’t use when you mean printer port.
lock Users lock documents or applications; they write-protect their disks. Disks
are copy-protected by the manufacturer.
logical operators Don’t use as verbs.
Correct: Using OR to combine x and y produces the result TRUE if either
one is true or if both are true.
Incorrect: ORing x and y produces the result TRUE if either one is true or
if both are true.
Correct: The directive uses the logical operator AND to compare the
accumulator contents with the contents of memory specified by the
operand.
Incorrect: The directive logically ANDs the accumulator contents with
the contents of memory specified by the operand.
In addition, do not use the symbols of logical operators in place of words in
sentences.
Correct: A task receiving a message it does not recognize must check
whether using AND to compare mCode and 0x8000 returns a value of
TRUE.
Incorrect: A task that receives a message that it does not recognize must
check if mCode & 0x8000 returns a value of TRUE.
log in (v.), login (adj.) In the UNIX system, you log in (not log into) to identify
yourself as a user (compare log on). Don’t use login as a noun or a verb. When
referring to the command, use lowercase computer voice.
Correct: You log in to the UNIX system using the login command.
Incorrect: You log into the UNIX system using the login command.
Correct: Use an administrative login operation for a specialized system
task.
Incorrect: Use an administrative login for a specialized system task.
log off (v.), log-off (adj.) In AppleShare, you log off a file server. Don’t use logoff
or logout in discussing the AppleShare environment. Don’t use log-off as a noun.
60
Style and Usage
log on (v.), log-on (adj.) In AppleShare, you log on to (not log onto) a file server.
Don’t use logon or login in discussing the AppleShare environment. Don’t use logon as a noun.
log out (v.), logout (adj.) In the UNIX system, you log out to end your work
session. Don’t use logout as a noun or a verb. When referring to the command, use
lowercase computer voice.
look up (v.), lookup (n., adj.) Spell the verb as two words; close up the noun or
adjective.
lo-res Don’t use; use low resolution (n.), low-resolution (adj.).
low bit (n.), low-bit (adj.) Note hyphenation of adjective. Not lo bit or lo-bit. Low
bit is an acceptable short form of the noun low-order bit.
lowercase (n., adj.) One word, no hyphen. When used in conjunction with
uppercase as a noun (or to modify a noun), use uppercase and lowercase (both
words spelled out, in that order).
low-order bit (n.) Not lo bit or lo-bit. Low bit is an acceptable short form.
low resolution (n.), low-resolution (adj.) Not lo-res. The short form low-res
(n., adj.) is OK when space constraints don’t allow use of the full phrase (as in
column heads in tables).
L2 cache See level 2 cache.
Mac, Mac PowerBook, Power Mac Don’t use Mac as a noun or as shorthand for
Macintosh; your Macintosh, not your Mac; Macintosh-compatible, not Maccompatible. Don’t use in model names; Power Macintosh 8600, not Power Mac
8600; Macintosh PowerBook, not Mac PowerBook. Use Mac only in the term Mac
OS (referring to the Macintosh Operating System). Don’t shorten Mac OS to Mac.
See also Mac OS.
machine Don’t use when you mean computer.
machine language (n.), machine-language (adj.) Note hyphenation of adjective.
Macintosh Use Macintosh to describe computers manufactured by Apple
Computer, Inc. Use Macintosh-compatible to describe hardware or software that
works with the Macintosh Operating System (Mac OS).
Macintosh is most correctly used as an adjective, as in Macintosh computer. When
using Macintosh as a noun, place an article or a possessive before it to avoid
anthropomorphizing (the Macintosh, your Macintosh).
Don’t use the plural (Macintoshes) in describing any of the Macintosh-family
computers. If you must describe any Macintosh computer in the plural, add the
word computers (Macintosh computers). Rewrite to avoid possessive forms of any
Macintosh product name.
Style and Usage
61
Use the full Macintosh computer model name (including model number) on the
manual cover and title page. Avoid using the full model name in text. For example,
refer to your computer or the Macintosh computer instead of the Power Macintosh
8600.
When a trademarked product name includes the word Macintosh, the full name
must be used (excluding model numbers): Macintosh G3. (An exception: After first
mention of the Macintosh Classic, it’s OK to use Classic.)
Do not use 128K, 512K, 512K enhanced, Plus, SE, II, LC, Centris, or Quadra alone,
except when it is necessary to list several models (example: “This software does
not work on the Macintosh 128K, 512K, or 512K enhanced.”). To avoid a string of
product names in a sentence or passage, use your Macintosh, the Macintosh, or
simply your computer.
The Macintosh 128K, Macintosh 512K, and Macintosh 512K enhanced are original
Macintosh computers. The Macintosh Plus, Macintosh SE, Macintosh SE/30, and
Macintosh Classic are compact Macintosh computers. Macintosh computers with a
separate monitor are modular. There are two kinds of modular Macintosh
computers: desktop and tower (or minitower). Current models with a built-in
monitor have the name all-in-one, but don’t use this name in documentation;
instead, describe the relevant features.
When describing the startup icons, use “happy Macintosh” and “sad Macintosh”
in quotation marks. Don’t use happy Mac or sad Mac.
Here is a list of Macintosh model names; note capitalization.
Macintosh 128K
Macintosh 512K
Macintosh Classic II
Macintosh II
Macintosh IIcx
Macintosh LC
Macintosh LC 630 DOS Compatible
Macintosh Performa 630
Macintosh Performa 5300CD
Macintosh Quadra 840AV
Macintosh SE
Power Macintosh 5200/75 LC
Power Macintosh 5260
Macintosh G3
Macintosh Server G3
Macintosh PowerBook 2400
Macintosh PowerBook G3
Macintosh file sharing Note lowercase. Use when it’s necessary to specify the
platform; otherwise, it’s preferable to use just file sharing.
62
Style and Usage
Macintosh G3 computers Don’t use G3 Macintosh, G3 Power Macintosh, or G3
computer.
Macintosh Operating System Note capitalization. Mac OS is preferred. See also
Mac OS.
Macintosh PC Exchange OK to shorten the name to PC Exchange.
Macintosh PowerBook Use full name on first occurrence; thereafter,
OK to shorten to PowerBook. See also PowerBook.
Macintosh Server G3 Note capitalization. Not Macintosh G3 Server.
Mac OS Two words. Short for Macintosh Operating System. Use with an article
(the Mac OS is…), except when it includes a version number (Mac OS 8.5). Use
Macintosh-compatible to refer to a computer that uses the Macintosh Operating
System.
Use Mac OS to refer to any version of Macintosh system software later than 7.6. See
also system software.
Mac OS Extended format Note capitalization. Mention on first occurrence that
this is also called HFS Plus; thereafter, use Mac OS Extended format. See also HFS
Plus.
Mac OS Standard format Note capitalization. Mention on first occurrence that
this is also called HFS; thereafter, use Mac OS Standard format. See also HFS.
main logic board Not motherboard or main circuit board. You can also use
main board.
main memory Not central memory.
main unit Refers to a Macintosh computer with nothing attached; don’t use
central processing unit or CPU for this purpose.
male connector Don’t use; use plug. See also connector.
manual Use to refer to a printed book that comes with a computer or other
product. Can also use user’s manual. Don’t use user’s guide. You can also refer to
online documentation such as a PDF file as an electronic manual. To refer to
documentation that may be either printed or online, use documentation (the
documentation that came with your computer).
Style and Usage
63
manual titles Use italics for full titles; in onscreen text, you can use quotation
marks.
Use caps/lowercase as used in the title. The article the is not usually part of the
manual title. Always give the title exactly as it appears on the manual cover (but
eliminate any trademark symbols). Don’t change an old title to comply with the
current guidelines for naming manuals.
When referring to an edition number, use lowercase and spell out both the ordinal
number and edition.
Technical Introduction to the Macintosh Family, second edition
Generic references to manuals are neither capitalized nor italicized.
See the user’s manual that came with your printer.
In user documentation, printed books are usually called manuals. The word guide
is usually reserved for onscreen help that uses Apple Guide technology. See also
Apple Guide; cross-references; parts; volume (book).
marginal gloss A marginal gloss is used to define a key term when it first appears
in the text or to make a cross-reference to another section or chapter. If you
prefer, you can incorporate some or all definitions and cross-references in
running text rather than use marginal glosses.
Marginal glosses can be used only in books with wide left margins.
In general, use marginal glosses for definitions only when the information will
provide supplemental help for some readers. If the material is indispensable to an
understanding of the text or defines a term that nearly all readers are unlikely to
know, it belongs in running text rather than in a marginal gloss.
Use marginal glosses consistently throughout a manual. For example, don’t use
them in one chapter to define terms that most readers will know and in another
chapter to define only very specialized or technical terms.
Use marginal glosses sparingly; they lose their impact if they appear too often and
sometimes even collide with one another or with marginal art if you try to fit
several on a page.
When using marginal glosses for definitions, boldface the defined term both in the
text and in the gloss. Any term that is defined in a marginal gloss must also be
included in the glossary, but the converse is not true: Not every term in the
glossary need appear in a marginal gloss at first use in text. For guidelines on
treating terms that appear in the glossary, see glossary.
Avoid using computer voice in marginal glosses in user manuals. If you use
fractions in marginal glosses, use unkerned fractions (that is, with numerator and
denominator on the line). See also fractions.
mass storage device No hyphen. OK in reference to a hard disk drive, a tape
backup unit, or a CD-ROM drive but not in reference to a 3.5-inch disk drive.
may See can, may.
64
Style and Usage
MB Abbreviation for megabyte. Spell out on first occurrence.
The adjective form is not hyphenated: 20 MB hard disk.
In the noun form, a space separates the numeral and the abbreviation, and the
preposition of is necessary before the unit that the value quantifies: 20 MB of
memory.
Mbit (sing. n., adj.), Mbits (pl. n.) Abbreviations for megabit and megabits. Spell
out on first occurrence.
The adjective form is hyphenated: 10-Mbit memory.
In the noun form, the preposition of is necessary before the unit that the value
quantifies: 10 Mbits of memory.
Mbps Abbreviation for megabits per second. Spell out on first occurrence.
measurement See Appendix B, “Units of Measure.”
megabit See Mbit, Mbits.
megabits per second Abbreviated Mbps. Spell out on first occurrence.
megabyte See MB.
memory address, memory location OK to use just address or location for
brevity. Don’t use commas even in numbers of five digits or more.
memory expansion card Lowercase in generic references.
menu bar Two words.
menu command Use command or menu command in user manuals; don’t use
menu option. Use menu item to refer to items that aren’t commands, such as items
in the Apple menu and programs in the Application menu. A menu command is in a
menu, not on or under a menu; a menu contains commands. See also Application
menu; command names; submenu.
menu titles Note capitalization: Edit menu, File menu, and so on.
menu types Note hyphenation: pop-up menu, pull-down menu, tear-off menu.
(Refer to the Macintosh Human Interface Guidelines for a description of each
menu type.) The names of menu types used in the Windows interface, such as dropdown menus, are also hyphenated.
metasymbols Refers to artificial terms that have meaning only in your manual
and are to be replaced by a value or symbol. In running text, use italic regular text
font when referring to a metasymbol, and spell out the metasymbol just as it
would appear in a syntax description. Use plain style when using the name of a
metasymbol in ordinary prose.
Correct: Replace volume-name with a name of up to 12 characters.
Correct: The volume name may have up to 12 characters.
Incorrect: The volume-name may have up to 12 characters.
See also syntax descriptions and Appendix A, “Technical Notation.”
Style and Usage
65
mice Don’t use; use mouse devices.
micro disk, micro diskette, microfloppydiskette Don’t use; use disk.
MIDI Acronym for Musical Instrument Digital Interface. Spell out on first
occurrence.
MIME Abbreviation for Multipurpose Internet Mail Extension. Use as an adjective
(a MIME file).
mini (prefix) Hyphenate before a word beginning with a vowel; close up before a
word beginning with a consonant.
mini-assembler, miniwindow, minicircular connector
minicircular connector Use 8-pin minicircular connector on first occurrence
(except in user manuals); thereafter, minicircular connector is fine. Don’t use
minicircular-8 connector. See also connector.
minitower One word; no hyphen.
m Figure 11
Miniwindows
miniwindow Refers to a box appearing in some applications that has some but
not all features of a regular window (see Figure 11). Don’t use windoid.
minus sign Not minus symbol. Use an en dash (generated by pressing Optionhyphen) for a minus sign (except in computer voice, where a hyphen is used).
MIPS Acronym for million instructions per second. Spell out on first occurrence.
Don’t drop the s when you are referring to a single unit: one MIPS, not one MIP.
mixed-directional (adj.) Note hyphenation. Use to refer to a combination of leftto-right and right-to-left text within a single line (French and Arabic on one line,
for example). Compare bidirectional.
mode Avoid in user manuals when referring to software (for example, when
describing a paint program, say, “When you are using the paintbrush,” not
“When you are in paintbrush mode”). In technical documentation, when referring
to software, you enter or leave a mode; you don’t turn on or turn off a mode.
model Don’t use when you can use computer.
Correct: How you use this feature depends on which model of
Macintosh computer you have.
Correct: The setup guide that came with your computer provides
instructions.
Incorrect: The setup guide that came with your model provides
instructions.
modem port Note lowercase. Not phone port.
modifier key Use instead of control key in the generic sense for a key that affects
the action of other keys, such as the Option, Control, Esc, and Shift keys.
66
Style and Usage
modular Macintosh computer Macintosh computers that have separate
monitors, such as the Power Macintosh 9600. There are two types of modular
Macintosh computer: desktop computers, which are wider than they are tall; and
towers and minitowers, which are taller than they are wide.
module Don’t use when discussing the Control Strip; use portion (the Battery
Level portion of the Control Strip).
monitor Preferred to display, but display is an acceptable synonym for monitor
when referring to a product whose name includes Display.
monitor cable Not video cable. Use to refer to the cable between the monitor and
the computer. (Use monitor power cord for the cord that goes from the monitor to
the power source.)
monitor cord Don’t use; use monitor power cord or monitor cable, whichever is
appropriate.
monitor depth Avoid; use color depth.
monitor port Not video port. Use to refer to the port to which the monitor is
connected.
monospaced (adj.) Not monospace. See also fixed-width.
motherboard Don’t use; use main logic board or main board.
mount Avoid in user documentation. Use connect to. OK to use mount
in technical documentation and when discussing certain environments.
User documentation: You can connect to a shared disk by opening an
alias for that disk.
Technical documentation: To use a VAXshare file server, you log on to
the file server and then mount the volumes to which you want access.
mounted disk Avoid in user documentation. Use available disk.
Click the Desktop button to see a list of all available disks.
mouse-ahead (n., adj.), mouse ahead (v.) No hyphen in verb. Refers to the
queuing of the user’s mouse actions until an application is ready to process them.
Compare type-ahead, type ahead.
mouse and mouse terms Drop references to the mouse as quickly as possible.
Switch emphasis to the actions on the screen, such as clicking, dragging,
selecting, or choosing. See also choose; click; drag; press; select.
mouse devices Not mice.
mouse-down event Note hyphenation.
mouse scaling (n.), mouse-scaling (adj.) Note hyphenation of adjective.
mouse-up event Note hyphenation.
Style and Usage
67
MS-DOS Note hyphenation and capitalization.
multi (prefix) Hyphenate before a word beginning with a vowel; close up before a
word beginning with a consonant.
multicharacter, multicolumn, multi-user
multiple scan (adj.) No hyphen.
multiplication sign Not multiplication symbol.
Musical Instrument Digital Interface (MIDI) Note capitalization. Spell out on
first occurrence.
native applications No quotation marks.
Incorrect: “Native” applications are designed to take advantage of your
computer’s microprocessor.
Correct: For best performance, use a native application.
Net In user documentation, don’t use as a short form of Internet.
NetBIOS Note capitalization.
network Computers are on, not in, a network.
network computer (NC) Lowercase when used generically.
network extension Use to refer to a file of type adev.
newline (n., adj.) The character. One word.
newsgroup One word.
nickel-metal-hydride Note hyphens. Abbreviated NiMH.
9-pin connector Use a numeral (don’t spell out nine). Note hyphenation. Avoid
in user manuals—describe the connector by its size and shape, icon, or in another
way appropriate to the context, because it may have fewer than nine actual pins.
See also connector.
non (prefix) Close up except before a proper noun, a proper adjective, an
abbreviation, or an acronym, or when the resulting word would be difficult to
read; for example, non-ADB, non-keyboard device, non-Macintosh, non-mouse
device, non-operational state.
nonsexist language See fair language.
nonstartup disk Avoid when possible. Instead, use a disk that does not contain
system software or another appropriate phrase.
normal installation Not normal install. Note lowercase. You perform a normal
installation; you don’t do a normal install.
68
Style and Usage
Note Use the Note tag when alerting the reader to information that is relevant to
the procedure under discussion but that may not apply to all readers.
Use notes and other notices sparingly; they lose effectiveness if they appear too
often. Don’t use a Note tag immediately before or after a Warning or Important
notice, or immediately after a text head. See also Important; Warning.
Note Pad, Notepad The first refers to a small word-processing program in the
Apple menu. The second refers to the word-processing area in the Newton
operating system. See also Appendix D.
NuBus Refers to the expansion bus in some Macintosh computers. NuBus is a
trademark of Texas Instruments, Inc. Don’t refer to Apple NuBus or Macintosh
NuBus. Refer instead to the Apple implementation of the NuBus protocol.
null character Use for ASCII character $00. Don’t confuse with zero character
(ASCII $30).
numbers In general, spell out cardinal numbers from zero through ten unless
you are expressing numbers as numbers. (Use a numeral, no matter how small, if
you’re expressing numbers as numbers.)
You can attach as many as seven SCSI devices.
You can have as many as 31 characters in a filename.
The numeral 8 occurs eight times.
Spell out ordinal numbers from zero through ten. Form ordinal numbers larger
than ten by adding st, nd, rd, or th as appropriate. (Exception to The Chicago
Manual of Style.) Where two numbers appear together, consider spelling one of
them out.
There are sixteen 32-bit registers.
Use an en dash between numbers that represent the endpoints of a continuous
range: bits 3–17. Use full span for continuing numbers: 1998–1999, not 1998–99.
Some programming languages, such as Pascal, use two unspaced periods to
represent a range of numbers: 0..15. Use this form for number ranges in code
only. Use the en dash elsewhere.
Use numerals for units of measure (inches, feet, seconds), no matter how small the
number is. For a list of units of measure, see Appendix B, “Units of Measure.”
Numbers of the same category within a paragraph should all be numerals if any of
the numbers is over 10.
We have 25 Macintosh computers and 4 LaserWriter printers on the
network. (Computers and printers are the same category.)
There are two kinds of 32-bit registers, only one of which needs to be
saved. (Kinds of registers and bits are different categories.)
Don’t spell out the 8 in 8-pin minicircular connector or the 9 in 9-pin connector.
Style and Usage
69
Use numerals when referring to a specific address, bit, byte, chapter, disk drive,
field, key, pin, sector, slot, or track, or when expressing amounts of memory.
Rephrase to avoid starting a sentence with a number. If you must start a sentence
with a number, spell out the number. Always spell out numbers when expressing
an approximation.
In referring to numbers, use larger and smaller, not higher and lower.
In referring to software version numbers, use later and earlier. For example, refer
to system software version 7.1 or later.
Use a comma to point off numbers of five digits or more.
1024
65,536
But don’t use a comma in memory addresses or numbers representing
microprocessors.
$FFFF FFFF
68020 microprocessor
Form the plural of a number by adding an apostrophe and an s.
1’s, 5’s
Use numerals for numeric values in text except for zero in the same sentence as
nonzero.
ord(blue) returns 0.
Function fseek returns nonzero for improper seeks; otherwise, it
returns zero.
For very large numbers that are a power of 2, you can use the exponential form to
avoid a long string of digits—for example, 232. Numbers larger than 65,536 (216)
are good candidates for showing in exponential form. If there are numbers larger
and smaller than 65,536 in the same discussion, show the smaller numbers both
ways—for example, “x must be between 1024 (210) and 232.”
See also fractions.
number sign Not pound sign or number symbol to describe this character: #.
numeric (adj.) Not numerical, except when referring specifically to numerical
order. (Exception to American Heritage.) See also numerics.
numeric keypad Can be shortened to keypad. Don’t use numerical keypad or
numeric keyboard.
numerics (n., adj.) As a noun, numerics takes a singular verb. Use numerics
(not numeric) as an adjective in relation to the science of numerics.
numerics capabilities
numerics environment
70
Style and Usage
nutdriver One word.
offline (adj., pred. adj., adv.) One word.
OK Not okay.
on, onto In general, the preposition on is used with verbs that indicate place or
position. Onto is used with verbs that express motion. (An exception to this rule
is install. See install.)
The Apple Extras folder is on your hard disk.
Copy the file onto your hard disk.
Exception: First, install the software on your hard disk.
on-board video card OK in technical manuals, but don’t use in user manuals; use
built-in video card for video cards that are installed at the factory.
100Base-T Preferred in user documentation, although 100BASE-T is also correct.
See also 10Base-T.
1.4 MB disk An Apple high-density disk, used in the Apple SuperDrive. Call these
disks high-density disks, after you explain that their capacity is 1.4 MB.
1.44 MB disk MS-DOS high-density disk that can be read by the Apple
SuperDrive. Note that the capacity of Apple high-density disks is 1.4 MB.
on-hook, off-hook (n., adj.) Note hyphen.
online (adj., pred. adj., adv.) One word. Use to describe items to which the user
gains access over a network (you can also search an online database). Avoid when
referring to the state of being connected to a network (if you’re online); use
another appropriate term, such as connected to the network or logged in.
It’s OK to use online to describe items (such as tutorials or help files) on a local
disk (online help system); when possible, however, substitute a more specific
word, such as electronic or onscreen.
Acceptable: To learn more about the program, take the online tutorial.
Preferable: To learn more about the program, take the onscreen tutorial.
on/off switch Not on/off button. Note lowercase.
onscreen (adj., adv.) Note that the adjective is closed up.
onscreen text You can use quotation marks, not italics, for words as words,
letters as letters, and phrases as phrases, and for manual and disk titles.
onto See on, onto.
open You open icons, folders, documents, and applications. In user
documentation, avoid “open a window” and “open window.”
opening display Not splash screen; opening display, startup display, and startup
screen are all OK.
Style and Usage
71
operating system (n.), operating-system (adj.) Lowercase when used
generically. Capitalized in the phrase Macintosh Operating System.
Option-click Avoid in user documentation.
Option key Note capitalization.
option names For options and other onscreen elements of two or more words
whose names are initial cap only, use quotation marks in text to avoid misreading.
Click the box labeled “Keep lines together.”
original Macintosh character set Note lowercase. Not traditional
character set or Apple character set. Current Macintosh models use the
Standard Roman character set.
outline font Don’t use outlined font.
output (n., adj.) Avoid as a verb; use write to, display on, print on, or print to.
outside Not outside of.
page See Web page.
PAL Acronym for Phased Alternate Lines (a European color standard) or for
Programmed Array Logic (a type of integrated circuit). Spell out on first
occurrence.
palette Note spelling.
parenthesis (sing.), parentheses (pl.) Note different spelling of singular and
plural. See also punctuation.
parts Most manuals don’t need to be divided into parts; division into chapters is
usually sufficient. Good candidates for division into parts are manuals that
describe two or more separate products or two or more mutually exclusive
programs on the same disk, or manuals so long that division into parts is
necessary to make the organization clearer to the reader.
Since books are divided into parts when each part deals with a distinct topic, part
titles indicate that difference in subject matter. Roman numerals are usually used
for part numbers, but an individual publication group’s design style may specify
Arabic numerals.
In a manual with parts, chapter numbering continues uninterrupted from part
to part.
In references to specific parts of a manual, italicize the part title along with the
manual title. Use a colon to separate the title from the part title when you refer to
both. Use an em dash to separate the part number from the part title.
For more information, see the Apple LaserWriter 16/600 PS User’s Manual:
Part III—Troubleshooting.
See also volume (book).
72
Style and Usage
Pascal Note capitalization.
passive voice Whenever possible, don’t use; use active voice. Passive voice is
sometimes appropriate and necessary—when using the active voice would require
highly convoluted sentence structure or excessive anthropomorphism, for
example—but rewrite to avoid passive voice if you can.
In tutorials, a passive construction may be appropriate to avoid miscuing
the reader—that is, when describing an action that the user is not supposed
to try yet.
Explanation screen: An icon is selected by clicking it.
User-try screen: You try it. Click the icon.
paste Don’t capitalize unless you are referring to the Paste command by name.
You paste something using the Paste command; you don’t Paste it.
pathname One word. Note the treatment of these similar terms: device name,
filename, user name, volume name.
PC Avoid when referring to a personal computer. Use personal computer for
generic references and IBM PC to refer to the IBM personal computer. However, in
certain documents—such as networking documents—where frequent references
must be made to non-Apple systems, PC may be used to refer to IBM systems and
MS-DOS systems. Don’t use PC as a generic name for IBM PCs and MS-DOS
compatibles without first specifying in the document the use of PC.
PC Card Note capitalization. A card that conforms to the standard set by the
Personal Computer Memory Card International Association (PCMCIA). On first
occurrence, include parenthetical reference to PCMCIA cards: You use PC Cards
(PCMCIA cards) to. . . and so on. Type I, Type II, and Type III (note spelling and
capitalization) refer to the thickness of the card.
PCI Abbreviation for Peripheral Component Interconnect, a type of card or slot.
Spell out on first occurrence, but never thereafter.
P-code Stands for pseudocode. Note capitalization and hyphenation.
PDF Stands for Portable Document Format. Spell out on first occurrence.
Capitalize when referring to the file format; lowercase when referring to the
filename extension (Installation Manual.pdf). Don’t use a file in PDF format; use
a PDF file.
PDS Abbreviation for processor-direct slot. Spell out on first occurrence. Don’t use
PDS slot.
Style and Usage
73
percent One word. Always preceded by a numeral, no matter how small
the value.
1 percent
It’s OK to use the percent symbol (%) instead of the word percent in technical
appendixes, specification lists, and tables, or when the word must appear so many
times in a text passage that its use becomes cumbersome.
When describing a nonspecific quantity, use percentage, as in a small percentage
of the population.
Performa Use Macintosh Performa on first occurrence. A Macintosh Performa
that contains a PowerPC microprocessor is not called a Power Macintosh, but you
can refer to it as a PowerPC-based computer.
periods See ellipsis points.
peripheral Avoid as a noun, especially in user manuals. Use peripheral card or
peripheral device.
peripheral card Not accessory card. When appropriate, be specific: interface card.
Avoid peripheral as a noun, especially in user manuals.
Peripheral Component Interconnect (PCI) Note capitalization. Spell out on first
occurrence, but never thereafter.
peripheral slot Don’t use; use expansion slot.
Phased Alternate Lines (PAL) Refers to a European standard for displaying color
video. Spell out on first occurrence.
Phillips screw, Phillips screwdriver Note capitalization and spelling. Not Phillipshead screw or Phillips-head screwdriver.
phone numbers When giving phone numbers, don’t put the area code in
parentheses or include a leading 1; for example: 800-282-2732. The corporate
phone number for Apple Computer, Inc. is 408-996-1010.
phone port Don’t use; use modem port.
piggyback board Don’t use; use expansion board.
pin In user manuals, avoid referring to connectors by the number of pins
because the actual number of pins may not match the designation. Describe the
connector by its size and shape, icon, or in another way appropriate to the
context.
When referring to connectors in technical manuals, use a numeral and a hyphen
before pin: 9-pin, 11-pin, 25-pin, 50-pin. (Exception to the rule that numbers ten
and smaller are spelled out except when used as numerals per se.)
pinout (n.) One word.
pixel Short for picture element. Not synonymous with bit.
74
Style and Usage
play back (v.), playback (n., adj.) Note that the verb is two words.
plug Not male connector. See also connector.
plurals
m acronyms and abbreviations
To form the plural of an acronym or an abbreviation, add an s but no apostrophe.
ICs, RAMs, ROMs
m adjectives
Don’t add s to an adjective unless necessary. For example, it’s electronic circuit
but electronics engineer. Other words that fall into this class of adjectives are
graphic and graphics, communication and communications, numeric and
numerics.
m letters, characters, symbols
To form the plural of a letter, character, or symbol, add an apostrophe and an s.
p’s, 6’s, +’s
m nouns
Don’t use (s) to indicate that a noun can be either singular or plural. Spell out the
singular and plural forms if necessary; if possible, rewrite to avoid either
construction.
Incorrect: Initializing your hard disk(s)
Correct: Initializing your hard disk or disks
Preferable: Initializing hard disks
m product names
Form the plural of trademarked product names by adding the plural generic noun
to the singular product name used as an adjective.
Incorrect: Macintoshes, Quadras, LaserWriters
Correct: Macintosh computers, Macintosh Quadra computers,
LaserWriter printers
If a product name includes a generic noun as well as a trademarked adjective, form
the plural as you would with any noun.
Apple 3.5 Drives, LocalTalk Custom Wiring Kits
m words as words
Form the plural of a word italicized to show that it is used as a word by adding an
apostrophe and an s. Do not italicize the apostrophe or the s.
He had too many and ’s in the sentence.
Style and Usage
75
plus sign Not plus symbol.
P .M . Note small caps and periods. (Exception to the rule that abbreviations do
not include periods.)
point (n.) Use only when writing about font sizes. Don’t use as a synonym for dot
or to describe a place or spot on the screen.
point (v.) When describing the desktop interface, don’t use point as a verb
without first defining it for the reader.
First occurrence: Move the mouse to position the pointer on the Trash
icon. (This action is called pointing.) Then press the mouse button to
select the icon. (This action is called clicking the icon.)
Thereafter: Point to the Trash icon and click to select it.
Once the reader is familiar with basic mouse techniques, it’s often not necessary
to mention pointing at all.
Click the Trash icon or Select the Trash icon.
pointer OK in general references, but be specific whenever appropriate: arrow,
crossbar, crosshair, I-beam, wristwatch. (Figure 12 gives an example of each of
these pointers.) Cursor may be appropriate in describing other interfaces and in
technical manuals.
m Figure 12 Pointers
Arrow
Crossbar
Crosshair
I-Beam
Wristwatch
POP Acronym for Point-of-Presence or Post Office Protocol. Spell out on first
occurrence. When used as an abbreviation for Post Office Protocol, POP must
modify a noun (such as server or ID).
pop up (v.), pop-up (adj.) Note hyphenation of adjective.
pop-up menu Refer to pop-up menus by name if possible (the “Connect using”
pop-up menu).
port A location for passing data in and out of a computer. Don’t capitalize the
names of ports (modem port, printer port). See also connector.
possessives Form the possessive of a singular noun, including one that ends in
s, by adding an apostrophe and an s.
the computer’s power cord
the boss’s husband
76
Style and Usage
Form the possessive of a plural noun that ends in s by adding an apostrophe.
Form the possessive of a plural noun that does not end in s by adding an
apostrophe and an s.
the students’ curriculum
children’s requirements
Form the possessive of a proper noun or a proper name, including one that ends
in s, by adding an apostrophe and an s. Form the possessive of a plural proper
noun or proper name by adding an apostrophe.
Howard Hughes’s official biography
the Joneses’ computer
Rewrite to avoid forming a possessive of any product name, especially a product
name such as Power Macintosh 5500 or Color LaserWriter 12/660 PS.
PostScript Note capitalization. Don’t use small caps.
pound sign Don’t use; use number sign for this character: #.
PowerBook Note capitalization. Use Macintosh PowerBook and the full model
name on first occurrence; thereafter, it’s OK to use just PowerBook. When referring
to the PowerBook Duo, don’t shorten to Duo.
Don’t use laptop, notebook, or notebook computer to describe a PowerBook.
These are the names associated with the PowerBook Duo. Note capitalization:
PowerBook Duo—refers to the computer itself
PowerBook Duo System—refers to a PowerBook Duo connected to other
equipment
PowerBook Duo Dock—dock for short
PowerBook Duo Minidock—minidock for short
Here is a list of PowerBook model names; note capitalization.
Macintosh PowerBook 165c
Macintosh PowerBook 180
Macintosh PowerBook 190/66
Macintosh PowerBook Duo Dock
Macintosh PowerBook Duo 270c
Macintosh PowerBook Duo 2300c/100
Macintosh PowerBook 5300/100
Macintosh PowerBook 5300ce/117
Macintosh PowerBook G3
PowerBook computers that contain PowerPC microprocessors are not called
Power Macintosh computers. You can refer to them as PowerPC-based computers.
Style and Usage
77
Power button, power button Use Power button (uppercase) to refer to the
button on the keyboard marked with the ® icon. Use power button (lowercase) to
refer to the same button on the computer, monitor, or other product. See also
Power key; power switch.
power cord Not power cable.
power-down (n., adj.), power down (v.) OK in technical manuals. Don’t use in
user manuals; use switch off or turn off.
Power key Note capitalization. Use to refer to the key on the keyboard marked
with the π icon. See also Power button, power button; power switch.
Power Mac Don’t use; use Power Macintosh. See also Power Macintosh.
Power Macintosh Use only to refer to computers in the Power Macintosh series.
Other computers that contain PowerPC microprocessors (such as some Macintosh
Performa or Macintosh PowerBook computers) are not Power Macintosh
computers. (It’s OK to refer to these computers as PowerPC-based computers.)
power off (v.) Don’t use, especially in user manuals; use switch off or turn off.
power on (v.) Don’t use, especially in user manuals; use switch on or turn on.
power-on light Note hyphenation and lowercase.
PowerPC One word. Use PowerPC-based computer to refer generically to
computers with a PowerPC microprocessor. See also Power Macintosh.
power switch OK to use when you’re not sure what kind of power control a
device has. Otherwise, use Power button or Power key. See also Power button,
power button; Power key.
power-up (n., adj.), power up (v.) OK in technical manuals. Don’t use in user
manuals; use switch on or turn on.
PRAM Stands for parameter random-access memory. Can also use parameter
RAM. Spell out on first occurrence. Pronounced “PEA-ram.”
pre (prefix) Close up even when it forms a double vowel, as in preexisting.
preface Not all manuals need a preface, but it’s often a good idea to include one,
especially in longer manuals.
The preface can be used to tell the reader about the manual, to describe
conventions such as special notation (for example, computer voice), and
emphasis for defined terms, and to outline what the reader will find where. As a
rule, discussion of the product belongs in the text, not in the preface, although it
is sometimes appropriate to include introductory information about the product
in the preface.
The preface should have a title. “About This Manual” is often appropriate.
When referring to the preface of a manual (but not when referring to prefaces in
general), capitalize the word preface.
See the Preface for more information.
preset May be used to describe a default setting.
MacWrite provides you with a ruler that has preset margins.
78
Style and Usage
press Use for keys on the keyboard and mechanical buttons and switches to
mean pressing down and releasing. Don’t use click, hit, tap, or type.
Press the Return key.
Press x-Q to quit HyperCard.
Use for buttons on the screen or the mouse button to mean only pressing down,
without releasing.
To click, press and release the mouse button.
Press the New button to see a list of memo forms, then drag to the form
you want.
See also click; enter; type.
print (v.) Not print out.
printed-circuit board Note hyphenation.
printer port Note lowercase.
print head Two words.
printout (n.) One word.
print out (v.) Don’t use; use print.
print server Two words.
print wheel Two words.
processor-direct slot Use processor-direct slot as the general term for an
expansion slot that allows an expansion card to be connected directly to the
central processing unit of the computer (rather than through a bus). Can be
abbreviated PDS. Not PDS slot.
product names Follow the capitalization style on the product’s packaging.
Don’t capitalize words like card and driver unless they are part of the product
name. Don’t use quotation marks around product names.
When you use a ™ or an ® symbol, the product name must be an adjective.
QuickTime® software
Macintosh® computer
Use the company name (Apple) with the product at its first use in both the preface
and main text to establish ownership of the product. Thereafter, it’s OK to drop
the name of the company.
See also trademarks.
program In user manuals, when referring to a single application program, use
application program on first mention; thereafter, it’s OK to use either application
or program. Use application software or software to refer to application software
in general.
program listings Use computer voice.
Style and Usage
79
Programmed Array Logic (PAL) Spell out on first occurrence.
program names Don’t use computer voice. Capitalization should agree with the
directory or catalog listing. Don’t confuse a program name with a product name.
One of the program files used for Windows NT version 3.5 is named
PSCRIPT.HLP.
To open Project Builder, find ProjectBuilder.app in the list of files and
double-click it.
See also product names.
prompt (n., v., adj.) Avoid as a verb except in reference to what the system does
when it displays an actual prompt character on the screen.
The prompt reminds you to do something.
The system then prompts you for information [with a prompt character].
The prompt character is sometimes a bracket.
pronunciation Whenever the pronunciation of an acronym is not self-evident, it’s
a good idea to give a pronunciation key. Use all caps for the stressed syllable; use
a hyphen between syllables. Enclose the phonetic spelling in quotation marks.
SCSI (pronounced “SKUH-zee”)
This style guide provides pronunciation keys for many acronyms; don’t invent
your own pronunciation key unless the pronunciation isn’t given in this
document.
propeller Not propellor.
protocol When referring to specific AppleTalk protocol names, capitalize protocol;
for example, the Name Binding Protocol (NBP). When referring to protocol names
in third-party products, capitalize according to the third-party company’s style.
When using protocol as a generic term, use lowercase.
The AppleTalk protocols can be placed in the framework of the ISO-OSI
model.
Use an article before the spelled-out name of the protocol; do not use an article
before the abbreviation when it stands alone.
The Name Binding Protocol resides at the transport layer of the reference
model.
A protocol like NBP resides at the transport layer of the reference model.
pseudo (prefix) Close up except before o, a proper noun, or a proper adjective.
(Hyphenate in those cases.)
pull down (v.), pull-down (adj.) Note hyphenation of adjective. The verb open is
preferred to pull down (open the File menu, not pull down the File menu).
80
Style and Usage
punctuation In general, a punctuation mark should be in the same type style and
font as the preceding word.
This address, called a vector, directs program control to a specified
destination. [The second comma is italicized.]
See the glossary for the definition of word wrap. [The period is
boldfaced.]
Note the following exceptions to this rule:
m Punctuation following computer voice in running text should be in the font of
the overall sentence, not in computer voice, unless the punctuation mark is
part of what actually appears on the screen or in the program listing. Avoid
punctuation after something the user should type. (The user may type the
punctuation.)
m A closing parenthesis, bracket, or quotation mark should be in the same style
as the opening mark. (For example, a closing parenthesis following an
italicized word should be in plain style, not italic, unless all text between the
parentheses is italicized.)
m When forming the plural of an italicized letter used as a letter, a number used
as a number, or a word used as a word, neither the apostrophe nor the s is
italicized.
For punctuation of lists, see lists.
See also apostrophes; commas; dashes; ellipsis points; hyphenation;
quotation marks.
put Don’t use when you mean drag.
Incorrect: Put the file in the System Folder.
Correct: Drag the file to the System Folder.
question-mark menu, question-mark icon Don’t use; use Guide menu.
QuickDraw The correct version names are original QuickDraw (not classic
QuickDraw), original Color QuickDraw, 32-Bit QuickDraw (a system extension
used with System 6), and in System 7, Color QuickDraw. Note capitalization.
QuickDraw GX is not a version of QuickDraw; it’s a separate graphics
programming environment.
QuickDraw GX Note capitalization. Do not use GX by itself or in any names
other than QuickDraw GX and TrueType GX; for example, don’t use
Printing Manager GX.
quick reference card No hyphen. A copyright notice should appear on all quick
reference cards:
Copyright © <year> Apple Computer, Inc. All rights reserved.
QuickTime VR VR stands for virtual reality. Don’t use QTVR.
quit You quit, exit from, or leave a program. You never exit a program. Compare
abort; cancel; exit; halt; interrupt; stop.
Style and Usage
81
quotation marks Use curly opening and closing quotation marks except in
computer voice and for Macintosh resource types in any font.
Put periods and commas within quotation marks. If necessary for clarity, periods
and commas can go outside, as in AN$ = “1”. Semicolons, colons, question marks,
and exclamation points go outside quotation marks unless they are part of an
actual quotation.
When giving the name of a resource type, use straight single quotation marks in
computer voice and place any punctuation outside the quotation marks.
Examples of resource types are 'FONT', 'NFNT', and 'cdev'.
Use quotation marks, not quote marks or quotes. (Quote is a verb; quotation is a
noun or an adjective.)
Use quotation marks for
m cross-references to other sections of the manual
See “Maintenance” at the end of this chapter.
m cross-references to chapter titles
See Chapter 2, “Using MacProject.”
m direct quotations
You can also use quotation marks in text that is read only on the screen for letters
as letters, words as words, and manual and disk titles.
In manuals, use italics, not quotation marks, for terms after called, known as,
labeled, stands for, termed, and so on. If a term is an element read only on the
screen, you can use plain style for elements whose names are caps/lowercase,
quotation marks for elements whose names are initial cap only.
INIT stands for initialize.
A folder named New Folder appears.
Click the checkbox labeled “Keep lines together.”
Enclose quotations from the screen, such as error messages or system messages,
in quotation marks.
Most applications have an option called “smart” quotation marks, which
automatically generates curly quotation marks when you press the ‘ or “ key.
82
Style and Usage
racism, racist language See fair language.
m Figure 13
Radio buttons
radio button Refers to an onscreen button like the ones shown in Figure 13. Use
only in technical documentation; use button in user manuals. No quotation marks
around radio; no hyphen. See also button.
radio-frequency interference (RFI) Note hyphenation. Spell out on first
occurrence.
radio-frequency (RF) modulator Note hyphenation. Use RF modulator only after
spelling out on first occurrence. Don’t abbreviate as RFM.
RAM Acronym for random-access memory. Spell out on first occurrence.
RAM cache (n.) Lowercase c except when referring specifically to the RAM Cache
option in the Control Panel in System 6.
RAM disk Two words. Note capitalization.
random-access memory (RAM) Note hyphenation. Spell out on first occurrence.
re (prefix) Usually closed up, even when it forms a double vowel, as in reenter.
Exception: re-create (as in re-create the file).
Read Me The name of a SimpleText document or other document, often shipped
with a software product, that contains information the user needs to read. Two
words; note capitalization. Read Me modifies a noun, usually file or document:
Open the Read Me files, not Open the Read Mes.
read-only memory (ROM) Note hyphenation. Spell out on first occurrence.
read/write (adj.) Note slash, as in read/write memory.
real time (n.), real-time (adj.) Note hyphenation of adjective.
recommend Avoid passive or first-person constructions that use recommend;
reword in terms of the user or product. In more formal contexts, such as a warning
tag, recommend is acceptable. Avoid Apple recommends.
Acceptable: For best performance, 16 MB of RAM is recommended.
Preferable: For best performance, your computer should have 16 MB of
RAM.
reference Don’t use as a verb; use refer to.
register Capitalize names of specific registers, but don’t capitalize the word
register. Don’t capitalize generic register names such as bank register and control
register.
release Don’t use when referring to a system software version number. See also
system software.
Rescued items from [volume name] Not Rescued Items Folder.
Style and Usage
83
Reset The button or switch, which may be labeled with the word Reset or with a
triangle symbol.
resizable Not resizeable.
resize Not size or grow. OK to write change the size of.
resize box Don’t use; use size box.
resolution Use a lowercase letter x (not the word by) to express screen
resolution (640 x 480).
resources and resource types A resource type name should be in computer
voice and must have exactly four characters inside straight, single, computer voice
quotation marks; for example, 'INIT', 'crsr', 'ICN#', and 'snd'. Resources
themselves are often referred to by the same abbreviation as their resource type,
but in a generic way; use regular text font in this case. Be sure to explain the
abbreviation on first use. Avoid using the resource type name abbreviation
unnecessarily.
Incorrect: Format 1 and format 2 snd resources . . .
Correct: Format 1 and format 2 sound resources . . .
Correct: Format 1 and format 2 'snd'resources . . .
Correct: All initialization resources, or INIT resources, are of type
'INIT'.
Correct: Resources of type 'XCMD'are HyperCard external commands
(also called ex-commands or XCMDs). When you write XCMDs . . .
Correct: To be adopted by the Control Panel, a cdev file must contain at
least these resources: 'DITL', 'mach', . . . and 'cdev'.
Return The key.
When you press Return, you generate a return character.
In technical manuals, it’s OK to use the Return symbol (å) in lines of code and in
tables.
return character Not carriage return or CR, except in technical documentation
when referring to ASCII character $0D. See also carriage return (CR).
RFI Abbreviation for radio-frequency interference. Spell out on first occurrence.
Right Arrow The key. When referring to more than one of the arrow keys, arrow is
lowercase (as in the arrow keys).
right-hand Avoid except in reference to right-hand (recto) pages; use just right
whenever possible.
84
Style and Usage
rightmost No hyphen.
right side Not right-hand side.
RISC Acronym for reduced instruction set computing. Spell out on first
occurrence.
road map Two words.
ROM Acronym for read-only memory. Spell out on first occurrence.
Roman, roman (adj.) Capitalize when referring to numerals; lowercase when
referring to type style. See also Arabic.
ROM disk Two words. Note capitalization.
router Don’t use interchangeably with bridge. A bridge joins two networks to
form an expanded network, not an internet. A router maintains a logical map of the
networks and other routers in an internet, allowing the networks to retain
separate identities.
RS-232-C Note hyphenation. Similar terms are hyphenated in the same way.
run (v.), running (adj.) In user documentation, use open (not running) to
describe an application program that is currently open.
Incorrect: Check to see if any applications are running.
Correct: Quit any open applications.
Say use (not run) to describe what a user does with a program. To describe
versions of system software, use a computer with (or that has) system software
version X.X, not a computer running system software version X.X.
runtime (n., adj.) One word, no hyphen.
“sad Macintosh” Refers to the startup icon. Use quotation marks. Not sad Mac.
sans serif (adj.) No hyphen. Not sanserif.
save box Don’t use; use close box.
save on a disk Not save to disk.
Scrapbook Note capitalization.
screen Not display.
script system Not script interface system. When appropriate, refer to a script
system by its product name, which may or may not include the words script
system. Don’t capitalize generic references to types of script systems.
KanjiTalk is Apple’s version of the Japanese script system.
The Roman Script System is available on all Macintosh computers.
Style and Usage
85
scroll Avoid using as a transitive verb.
Correct: Scroll through a document.
Correct: Scroll to view more of the document.
Incorrect: Scroll a document.
scroll arrows Two words; not scroll bar arrows.
scroll bar Two words.
scroll box Two words.
SCSI Acronym for Small Computer System Interface. Spell out on first occurrence.
The acronym is pronounced “SKUH-zee,” so it is preceded by a, not an.
The DVD-ROM drive is a SCSI device.
You can connect Narrow SCSI devices to the computer’s external SCSI
port.
Different types of SCSI connections are named according to their speed. Note the
treatment of these terms: Narrow SCSI (also called SCSI-1), Fast Narrow SCSI (also
called SCSI-2), Fast Wide SCSI, Wide Ultra SCSI, Wide Ultra2 SCSI.
SCSI cable Not SCSI system interface cable or SCSI interface cable. Be specific:
SCSI system cable, SCSI peripheral cable.
SCSI card Not SCSI interface card.
SCSI ID indicator Not SCSI priority switch.
SCSI ID number Not SCSI priority number.
SCSI ID switch Not SCSI priority switch setter or SCSI ID number switch.
secondary cache, second-level cache Don’t use; use level 2 cache or L2 cache.
section, section record Avoid in user documentation; use publisher or
subscriber.
select Use select, not choose, for icons, windows, objects, graphic images,
sections of text, or options in dialog boxes. Use choose for menu commands,
including those in tear-off menus. See also choose. Compare deselect; highlight;
unselected.
self-test (n., adj.) Note hyphenation. Don’t use as a verb.
sentence style Another name for initial cap only, a style of capitalization. In
sentence style, only the first letter of the first word is capitalized. See also
capitalization.
setup (n., adj.), set up (v.) One word except as a verb.
86
Style and Usage
sexism, sexist language See fair language.
SGRAM Abbreviation for synchronous graphic random-access memory. Spell out
on first occurrence.
shared disk In user documentation, use shared disk when you discuss
connecting to another Macintosh over the network. When you discuss setting up
a folder to share on your own computer, use shared folder. Use file server only
when explaining the concept of file servers.
shared folder In user documentation, use shared folder when you discuss
setting up a folder to share on your own computer. Use shared disk when you
discuss connecting to another Macintosh over the network. See also shared disk.
Shift The key. Note capitalization.
Shift-click (v., adj.) Note capitalization and hyphenation. (The hyphen denotes a
combined keystroke.) Avoid as a verb in user documentation; subsitute press the
Shift key and click if possible.
Use the Shift-click technique to select more than one icon.
Shift lock Don’t use; use Caps Lock.
shortcut One word.
sign Use sign, not symbol, in the following terms: division sign, equal sign,
greater-than sign, less-than sign, minus sign, multiplication sign, number sign,
and plus sign.
signaled, signaling Not signalled, signalling.
signals Use regular text font, all caps, for signal names. Use an en dash between
the first and last signal names to indicate a range of signals. Begin active-low
signal names with a slash, and use angle brackets to enclose two or more ranges
in a set.
/CLK
</AD31–/AD29,/AD7–/AD0>
SIMM Acronym for Single Inline Memory Module. Spell out on first occurrence.
SimpleText One word. Note capitalization.
since Can be used to mean because, but only if it begins a sentence. When using
since in this way, however, make sure it isn’t possible to misread the sentence as
an expression of temporal relationship.
Correct: Since the address is passed on every call, you must . . .
Incorrect: Using access privileges is a good idea, since you probably
won’t want all users to make changes to the document.
Style and Usage
87
Single Inline Memory Module (SIMM) Note capitalization. Spell out on first
occurrence.
single letters See letters as letters.
68000, 68020, . . . Don’t use a comma in a number representing a
microprocessor. In user documentation, if possible, don’t use to refer to
Macintosh computers that do not contain PowerPC microprocessors; use if your
computer does not contain a PowerPC microprocessor or a similar phrase. In user
documentation, don’t use 68K for 68000. On first occurrence, use Motorola 68000
microprocessor; thereafter, the manufacturer need not be mentioned. See also x.
size (v.) Don’t use; use resize or change the size of (in reference to a window or
an object).
size box Two words. Not grow box or resize box.
size region Don’t use; use grow region.
sleep An energy-saving feature of some computers. The computer goes to sleep
(or the user can put it to sleep); the computer is then in sleep or in sleep mode. Do
not say the computer is sleeping or asleep.
slot 1, slot 2, . . . Lowercase. The slot number is Arabic.
SMTP Abbreviation for Simple Mail Transfer Protocol. Spell out on first
occurrence.
so-called (adj.) Don’t italicize or use quotation marks around terms following
so-called.
socket Not female connector. See also connector; port.
software Use application software or software to refer to application software in
general. You can use application program, application, or program when referring
to a single program.
software license agreement Note lowercase.
sound input port Lowercase; no hyphen. Not sound-in port or Sound In port. The
port that connects the computer to a microphone or similar sound input
equipment. Compare audio input port.
sound output port Lowercase; no hyphen. Not sound-out port or Sound Out port.
The port that connects the computer to headphones, speakers, or other sound
output equipment. Compare audio output port.
source file Two words, except in reference to the Pascal predefined file type
sourcefile.
Space bar Two words. Note capitalization.
88
Style and Usage
space character Not blank or blank character. OK to use just space, but in many
cases it’s necessary to remind the user that a space is actually a character and that
margins, indention, word wrap, and page breaks can sometimes be affected by
extra space characters (or a lack of them).
spell-check (v.) Don’t use; use check spelling.
spelling checker Not spell checker.
splash screen Don’t use; use opening display, startup display, or startup screen.
spring open (v.), spring-open (adj.) In user documentation, not spring-loaded.
square wave (n.), square-wave (adj.) Note hyphenation of adjective.
stand-alone (adj.) Note hyphenation. Don’t use as a noun.
standard file dialog box In user documentation, don’t use. In many cases, it’s
not necessary to name the dialog box at all. When a name is necessary, use
directory dialog box or name the dialog box according to the context (Open dialog
box, Save dialog box, and so on).
Standard Roman character set Note capitalization.
start Don’t use when you mean open (open an application program).
start up (v.), startup (adj.) Avoid as a noun, especially in user manuals, except
when repeated occurrences of when you start up become unwieldy.
Start up the Macintosh.
Insert the startup disk.
See also boot.
startup disk Preferred term, but boot disk is OK in technical manuals.
startup display, startup screen Not splash screen; startup display, startup screen,
and opening display are all OK.
statement Not necessarily the same as line. One line may contain several
statements, and one statement may extend over several lines.
Style and Usage
89
state names Use the two-letter abbreviations shown in Table 1. (Both letters are
capitalized in these abbreviations.)
m Table 1 Abbreviations for state and territory names
__________________________________________________________________________
State
Abbreviation
State
Abbreviation
__________________________________________________________________________
Alabama
AL
Montana
MT
Alaska
AK
Nebraska
NE
American Samoa
AS
Nevada
NV
Arizona
AZ
New Hampshire
NH
Arkansas
AR
New Jersey
NJ
California
CA
New Mexico
NM
Colorado
CO
New York
NY
Connecticut
CT
North Carolina
NC
Delaware
DE
North Dakota
ND
District of Columbia
DC
Ohio
OH
Florida
FL
Oklahoma
OK
Georgia
GA
Oregon
OR
Guam
GU
Pennsylvania
PA
Hawaii
HI
Puerto Rico
PR
Idaho
ID
Rhode Island
RI
Illinois
IL
South Carolina
SC
Indiana
IN
South Dakota
SD
Iowa
IA
Tennessee
TN
Kansas
KS
Texas
TX
Kentucky
KY
Utah
UT
Louisiana
LA
Vermont
VT
Maine
ME
Virginia
VA
Maryland
MD
Virgin Islands
VI
Massachusetts
MA
Washington
WA
Michigan
MI
West Virginia
WV
Minnesota
MN
Wisconsin
WI
Mississippi
MS
Wyoming
WY
Missouri
MO
stationery pad In user documentation, not stationery document or stationery.
The checkbox in the Info window is labeled Stationery pad (note capitalization).
stationery-aware program Don’t use. Use program that supports stationery or
program that recognizes stationery.
90
Style and Usage
step Don’t capitalize, even in specific references.
step 1, steps 1 and 2, several steps
stereotypes See fair language.
stop A general term meaning to cause a process, command, or program to cease.
Compare abort; cancel; exit; halt; interrupt.
style (of type) Not typestyle or type style.
StyleWriter Use as an adjective, as in StyleWriter printer. Here are some examples
of model names:
StyleWriter II
Color StyleWriter 2500
subdirectory When describing the desktop interface in a user manual, use folder.
See also folder.
m Figure 14
A menu and a submenu
submenu Use when describing hierarchical menus (see Figure 14). When the
user drags the pointer to the side of a hierarchical menu command with a
triangular indicator, a submenu appears.
When the user must choose an item from a submenu, use this wording: Choose X
from the Y menu, then choose Z from the submenu.
Choose Control Panels from the Apple () menu, then choose Memory
from the submenu.
subnetwork No hyphen.
subtitles, manual See parts; volume (book).
SuperDrive See Apple SuperDrive.
support Avoid if possible in user documentation. Reword using alternatives
appropriate to the context, such as works with, provides, is available, has, or you
can use.
Incorrect: This version of system software does not support
background printing.
Correct: Background printing is unavailable in this version of system
software.
S-video Note capitalization and hyphen.
S-video input port A type of port on AV computers; connects the computer to
video equipment that uses an S-video connector. Not S-video In port. Different
from a composite video input port. (Compare video input port.)
S-video output port A type of port on AV computers; connects the computer to
video equipment that uses an S-video connector. Not S-video Out port. Different
from a composite video output port. (Compare video output port.)
switch on, switch off Don’t use power down, power off, power on, or power up in
user manuals. OK to use turn on and turn off.
Style and Usage
91
symbol OK in a generic sense, as in the percent symbol (%). Don’t use symbol
when you mean character, letter, or digit.
Use sign, not symbol, in the following terms: division sign, equal sign, greater-than
sign, less-than sign, minus sign, multiplication sign, number sign, and plus sign.
syntax descriptions Use computer voice for literals (parts of the language,
values, and so on), italic regular text font for metasymbols (artificial terms that
have meaning only in your book and are to be replaced by a value or symbol), and
plain style regular text font for brackets that enclose something that’s optional.
Pay close attention to punctuation.
Read ([file, ] var)
Use a hyphen or an embedded cap to connect two words that act as a single
metasymbol.
Correct: source-file or sourceFile
Incorrect: sourcefile or source_file
Be consistent when naming metasymbols; for example, don’t alternate between
commands and command-list.
system Use as a broad term; a system includes a computer and any peripheral
devices, accessories, and software. Don’t use system to refer to the computer
alone.
system extension In user documentation, may be used to describe files (for
instance, files of type 'INIT', 'appe', and 'seri') that extend the abilities of
the computer. Compare INIT.
System file Note capitalization. Refers to the specifically named file in the System
Folder. Compare system files.
system files Lowercase. Refers to any files used by the Macintosh to start itself
up or to provide system-wide information. Compare System file.
System Folder Note capitalization.
system menu Don’t use in user documentation.
System 6, System 7 Use this style to refer to system software “families” through
System 7.5. If it’s necessary to refer to specific version numbers in these families,
use system software version x.y.z. Exception: System 7.5. See also Mac OS; system
software.
system software Note lowercase. Not systems software. The way you refer to the
Macintosh system software depends on the version number you’re referring to.
pre-7.0—System 6, system software version 6.x.x
7.0–7.5.5—System 7, System 7.5.3
7.6 and later—Mac OS 7.6, Mac OS 7.6.1, Mac OS 8 (not 8.0), Mac OS 8.1
92
Style and Usage
Use in (or with) Mac OS x.x, not under Mac OS x.x.
In Mac OS 8.1, help is available in the Help menu.
When referring to system software version numbers, use later and earlier; for
example, refer to Finder version 7.5.5 or later.
The Power Macintosh 5200/75 LC requires System 7.5 or later.
system-wide (adj.) Note hyphenation.
Tab, tab Capitalize when referring to the key; use lowercase when referring to the
character or to the tab at the end of the Control Strip.
When you press Tab, you generate a tab character.
The tab character (HT, for horizontal tab) has ASCII value $09.
Click the tab at the end of the Control Strip.
table Use tables whenever numbers or text would be clearer if presented in rows
and columns.
Capitalization style for all parts of a table is initial cap only.
Column heads, spanners (heads to which at least two column heads are
subordinate), row titles (heads in the leftmost column), and stubs (heads to
which at least two row titles are subordinate) should be short and descriptive.
If it’s necessary to subdivide a single table into sections, use horizontal rules to
do so.
table caption Table captions include a table number (optional; refer to your
department’s design specifications) and a table title. If a table is so simple that it
needs no title, it should be reformatted as a list.
Table titles should be short; do not exceed a line and a half of text. Avoid using
complete sentences for table titles. Also avoid changing fonts and styles in table
titles (for example, avoid using computer voice).
When a table continues onto a second page, the table title is repeated and
followed by (continued). The table rules, spanners, and column heads are also
repeated. If the table continues onto a left-hand page, the word continued also
appears at the bottom of the previous page.
All tables need in-text references. In general, the reference belongs in the
paragraph preceding the table. Don’t use below or above to refer to a table. In-text
references can stand alone as a complete sentence (with or without parentheses),
or can occur within a sentence (with or without parentheses). Try to use a
consistent style throughout a document.
Style and Usage
93
table notes and table footnotes Information that pertains to an entire table is
generally set as a table note, before any table footnotes.
The table note begins with the word Note (initial cap only) followed by a colon. If
it is essential that this information be more prominent than a table note allows, it
can be added instead after the table title, in parentheses, with no capitalization or
ending punctuation (even if it is a complete sentence).
When specific items within a table require footnotes, depending on your
department’s style, either number the items consecutively starting with 1, or use
the following symbols, in this order:
asterisk (*)
dagger (†, Option-T)
double dagger (‡, Option-Shift-7 in the LaserWriter fonts Helvetica,
Times, Courier, and Garamond)
section (§, Option-6)
paragraph (¶, Option-7)
number (#)
The symbols *, †, and # are already superscript. The symbols ‡, §, and ¶ need to
be selected and made superscript. When more symbols are needed, they are
doubled, in the same order.
table of contents Most manuals of ten pages or more should have a table of
contents, which always begins on a new right-hand page.
The first page of the table of contents has a page number but no running foot; all
subsequent pages have both a page number and the running foot “Contents”
(for both right-hand and left-hand pages).
The table of contents should include part, chapter, and chapter-equivalent titles
and may include level-one, level-two, and level-three heads. If absolutely
necessary, level-four heads can be included (but remember that a book long
enough to need level-four heads will also have an index).
The wording, capitalization, punctuation, and spelling of all heads and titles must
be exactly the same in the text as in the table of contents.
See also chapter tables of contents.
tap You tap a trackpad or the screen on a Newton device. Don’t use when you
mean press. See also click; press; type.
TeachText One word. Note capitalization.
94
Style and Usage
m Figure 15
A tear-off menu
tear-off menu Refers to a menu that can be dragged from the menu bar and left
on the desktop either as a list of commands or as a palette. (See Figure 15.) Note
hyphenation.
telecommunicate Don’t use as a verb. Use communicate instead.
telecommunication Telecommunication refers to the act; telecommunications
refers to the field. When used as an adjective, the correct term is
telecommunications.
Telecommunication gets simpler by the day, though you can’t prove it
by most manuals on this subject.
The telecommunications industry is expanding rapidly.
television Not television set or TV set. After the first occurrence, TV is OK.
television monitor Don’t use. Use video monitor or monitor.
Telnet Note capitalization. Avoid as a verb. The UNIX command telnet is all
lowercase.
Correct: You use Telnet to connect to another computer as a terminal.
Incorrect: You Telnet to another computer to use its software.
Correct: You use the telnet command to connect to another computer
as a terminal.
10Base-T Preferred in user documentation, although 10BASE-T is also correct. See
also 100Base-T.
terminal emulation (n., adj.) No hyphen.
text field Don’t use; use text box.
text file Two words, except in reference to the Pascal predefined file type textfile.
text head Use different levels of text heads to make the organization of a manual
clearer to the reader, but remember that too many heads too close together will
distract the reader and clutter the page.
In general, organize your sections so that level-four heads are subordinate to
level-three heads, level-three heads to level-two heads, and so on. (Don’t skip a
level of heads.) When the next logical level of heading seems too prominent for a
given usage (in troubleshooting chapters, for example), try to use display
sentences rather than skipping a level of text heads.
In general, avoid beginning a chapter with a level-one head; start with an
introductory paragraph or two before your first text head. Likewise, avoid placing
a level-two head immediately after a level-one head, and so on. However, in cases
involving space limitations, or where text serves primarily to separate one head
from the next (but isn’t necessary to the user), it’s OK to place a head immediately
following the previous level of head.
Style and Usage
95
If you use a particular level of head at all in a given chapter or section, use at least
two. (Strictly speaking, a chapter or section can’t be subdivided into only one
part.)
The wording of parallel heads within a section should be parallel: verb forms
should be the same (gerunds, imperatives, and so on) from head to head;
comparable terms should all be either singular or plural, not a mix; and if you’re
using complete sentences for some heads, use them for all comparable heads.
Avoid cute, flippant, or gimmicky heads. Humor can be an effective means of
enhancing the reader’s experience, but it generally works best in the text rather
than in titles or heads. Count on your prose to create the excitement necessary to
carry the reader along; keep heads simple and descriptive.
The capitalization style for all levels of text heads is caps/lowercase, or title style.
Avoid colons in heads wherever possible. If a colon in a head is required, capitalize
the first word after the colon. Avoid ellipses in heads.
that Use to introduce a restrictive clause; clauses beginning with that are
generally not set off with commas. Compare which.
Correct: This is the house that Jack built. (There are many houses; the
phrase that Jack built restricts [narrows the meaning of] the subject of
the sentence to one house.)
Correct: The largest house in town, which Jack’s sister built, is also the
newest. (There is only one largest house; the phrase which Jack’s sister
built, although it provides more information, does not restrict the
subject of the sentence.)
thicknet One word, lowercase; no embedded capital.
thinnet One word, lowercase; no embedded capital.
third party (n.), third-party (adj.) The adjective is hyphenated. Avoid in user
documentation; if possible, replace with another descriptive term, such as not
made by Apple or from other manufacturers.
Avoid: You can also obtain software for your Newton device from thirdparty developers.
Preferred: If you’ve installed extensions from manufacturers other than
Apple, one of them could be causing the problem.
32-bit clean Note hyphenation. Don’t use cleanliness, uncleanliness, or unclean;
use not 32-bit clean.
32-Bit QuickDraw Note capitalization. Refers to a system extension
used with System 6.
96
Style and Usage
thread A series of related files, such as e-mail messages. Items are in a thread.
You can reply to an earlier message in the thread.
3D No hyphen.
3.5 Not 31⁄2 when referring to 3.5-inch disks.
throw away Don’t use when you mean to drag an item to the Trash.
Incorrect: Throw away the extension that’s causing the problem.
Correct: Drag the extension that’s causing the problem to the Trash.
thumb Don’t use when you mean scroll box.
time-consuming (adj., pred. adj.) Note hyphenation.
timeout (n., adj.) One word, no hyphen.
title bar Two words. Note lowercase.
titled Not entitled.
title page All manuals must have a title page. This page is the first in the book and
does not have a page number or a running foot.
titles, chapter and section Make part titles, chapter titles, and heads concise and
consistent. Keep the reader’s needs in mind, and remember that these elements
are used primarily as locators for someone skimming through a manual.
For functional definitions of design elements, see the design specifications for
your department.
titles, disk See disc or disk titles.
titles, manual See manual titles.
title style Another name for caps/lowercase, a style of capitalization. See also
capitalization.
titles, window See window titles.
toggle (v.) OK to use in technical documentation; do not use in user
documentation.
token ring network Three words. No hyphen. Note capitalization.
toolkit One word.
touch-tone (adj.) Note hyphenation.
toward Not towards.
trackball An input device used as a substitute for a mouse. One word.
trackpad One word.
Style and Usage
97
trademarks Any trademarked Apple product mentioned in a manual must be
mentioned in the appropriate credit line—for trademarks (™) or registered
trademarks (®)—on the copyright page. Credit lines for certain third-party
trademarked products must also be given on the copyright page (for a list of
those products, see the “Special and Licensed Trademarks and/or Copyrights”
section of the most recent Apple trademarks list, available at
www.apple.com/legal/publictmlist.html).
Trademark symbols are not included for Apple products in printed or electronic
manuals. Note, however, that trademark symbols are often included in other types
of documentation, such as marketing materials. Follow the usage guidelines
specific to your type of documentation.
Trademark symbols are included only for certain third-party products (listed in the
trademark list). Include the symbol on first occurrence in the preface and in the
text (and on the title page if applicable).
When a product name is trademarked, it should be used often throughout the
document as an adjective modifying a generic noun (particularly on first
occurrence in the preface and in each chapter). Avoid using a trademarked term in
the possessive or plural form.
Trademark status changes with time; for the most current Apple trademarks,
consult the trademark list published by the Apple legal department.
The following uses of a name do not constitute first occurrence in text and should
not receive a trademark: in a manual title used in a cross-reference, in a heading, in
a caption for a table or figure in a marginal gloss.
Trash Note capitalization. Use an article (drag the file to the Trash).
TrueType One word.
troubleshoot (v.), troubleshooting (n., adj.) One word.
turn on, turn off OK to use when describing power to a computer or
peripheral device.
tutorial steps Early in an instructional sequence, phrase tutorial steps to reflect
the sequence of the novice user’s action. Say “Open the File menu and choose
Open,” instead of “Choose Open from the File menu.” The latter phrasing is
appropriate for procedures in reference manuals and in later sections of tutorials
when the sequence of choosing from menus has been well reinforced.
TV Not TV set or television set. Use television on first occurrence, except in the
product name Macintosh TV.
TV monitor Don’t use. Use video monitor or monitor.
25-pin connector Note hyphenation. Avoid in user manuals—describe the
connector by its size and shape, icon, or in another way appropriate to the
context, because it may have fewer than 25 actual pins. See also connector.
twisted-pair cable Note hyphen.
98
Style and Usage
type (n.) Use in general references to the text that appears on a printed page.
Don’t use type when you mean font or font family.
type (v.) Use to describe the act of pressing keys to produce characters on the
screen. In manuals, use computer voice to represent what the user actually types,
regular text font to describe generically what the user types. For onscreen text,
standards are changing; at present, quotation marks are often (but not always)
used to represent what the user actually types. Don’t use type in when you mean
type.
Type PR#4.
Type Hello.
Type your name.
Compare enter; press.
type-ahead (n., adj.), type ahead (v.) No hyphen in verb. Refers to the queuing of
a user’s keystrokes until an application is ready to process them. Compare
mouse-ahead, mouse ahead.
typeface Use to refer to a distinct design for a particular character set. Each
typeface has its own name, such as Times or Garamond. Compare font.
Fonts of the same typeface (regardless of font style or point size, or
whether they are outline or bitmap fonts) form a single font family.
type family Don’t use; use font family.
type size Don’t use; use size or font size.
uncheck Don’t use; use deselect.
unclean Don’t use; use not 32-bit clean.
under Don’t use to describe an operating system environment. Use in or with
(in System 7, not under System 7).
underlining Don’t use in manuals. See also boldface; italics; quotation marks.
unhighlight (v.) Don’t use. Use deselect for the action of clicking to remove
highlighting.
unhighlighted (adj.) Don’t use; use not highlighted. Compare unselected.
Uniform Resource Locator (URL) See URL.
UNIX system A registered trademark. All caps, but not an acronym. UNIX is
correctly used as an adjective, as in UNIX system.
unprotect Don’t use; use remove protection.
unselected (adj.) Use to describe something that has not yet been selected. Not
deselected or dehighlighted. Compare deselect; unhighlighted.
Up Arrow The key. When referring to more than one of the arrow keys, arrow is
lowercase (as in the arrow keys).
Style and Usage
99
upgradable Not upgradeable.
uppercase (n., adj.) One word, no hyphen. When used in conjunction with
lowercase as a noun (or to modify a noun), use uppercase and lowercase (both
words spelled out, in that order).
upside-down (adj.) Note hyphenation.
upward Not upwards.
URL Abbreviation for Uniform Resource Locator, a way of specifying Internet
addresses. The abbreviation is pronounced “you-are-el,” so it is preceded by a,
not an. A URL can specify an address for a Web page, as well as a Gopher, FTP, or
Telnet site. Addresses that are expressed as URLs include prefixes for the type of
site they are used to access. For example, a URL for a Web page includes the prefix
http://, and a URL for a Telnet site includes the prefix telnet://. To describe general
concepts in user documentation, consider using address instead of URL, because
it’s easier for novices to understand. See also address; Internet address; Web
address.
U.S. Note periods. (Exception to the rule that abbreviations do not include
periods.) Use the abbreviation as an adjective only; as a noun, spell out United
States (except in copyright statements).
USB Abbreviation for Universal Serial Bus. Spell out on first occurrence. Avoid as
a noun.
Usenet Note capitalization.
user group Not users group or user’s group.
user name Two words. Note the treatment of these similar terms: device name,
filename, pathname, volume name.
user’s manual Not user manual or user’s guide. See also manual.
VAX/VMS Don’t use. Use a phrase such as VAX computers using VMS software.
Incorrect: VAX/VMS systems
Correct: VAX computers using the VMS operating system
version Lowercase, as in AppleShare version 1.1. Use later rather than higher in
phrases such as Finder version 6.0.2 or later.
versus Not vs. Rewrite to avoid using versus when possible.
video cable Don’t use to describe a cable connecting a monitor to a computer;
use monitor cable. OK to use for a cable that connects audio/video equipment,
such as a television or VCR.
video camera Two words.
videoconference (n.), videoconferencing (adj.) One word. Don’t use
videoconference as a verb; use a phrase such as have a videoconference.
100
Style and Usage
video input port Or composite video input port. Not video-in port or Video In port.
Port that connects the computer to most video equipment. Compare S-video
input port.
video jack Not video connector.
video output port Or composite video output port. Not video-out port or Video Out
port. Port that connects the computer to most video equipment. Compare S-video
output port.
video port Don’t use when you mean the port to which the monitor is
connected; use monitor port.
viewport One word. Don’t use when you mean window.
virtual memory Not Virtual Memory or VM.
voice mail Two words.
voice-quality microphone Note hyphen.
volume (book) Books are divided into volumes when page length exceeds
manageable limits. Different volumes don’t have different titles because the
division into volumes doesn’t represent a difference in subject matter. Use Arabic
numerals for volume numbers.
Volume 1, Volume 2
The first edition of Inside Macintosh is an exception to this rule; its volume
numbers are Roman. (The current set of Inside Macintosh books does not use
volume numbers.)
Volume VI of Inside Macintosh
In cross-references to specific volumes, capitalize but don’t italicize Volume.
See Volume 1 of the Applesoft BASIC Programmer’s Reference Manual
for more information.
See also parts.
volume (disk) In general, don’t use to refer to disks in user documentation; use
disk or the specific kind of disk you’re referring to. OK to use volume to refer to a
server or to individual partitions on a disk. Also OK to use volume to refer
generically to units of storage, when these may include a number of different kinds
of disks.
You can use the Find command to search for items on all volumes
connected to your computer.
volume name Two words. In specific references, capitalization of the volume
name should agree with the directory listing: the volume name is PERSONNEL.
Note the treatment of these similar terms: device name, filename, pathname,
user name.
Style and Usage
101
VRAM Stands for video random-access memory. Spell out on first occurrence.
Pronounced “VEE-ram.”
vs. Don’t use; use versus when absolutely necessary, but rewrite to avoid the
term when possible.
warm start (n.), warm-start (adj.) Note hyphenation of adjective.
Warning Use a Warning notice when the reader needs to know that an action
may cause bodily injury, damage to hardware or software, or loss of data.
Use warning notices and other notices sparingly; they lose effectiveness if they
appear too often. Don’t use a warning notice immediately before or after an
Important notice or Note tag, or immediately after a text head. See also Important;
Note.
waveform (n., adj.) One word.
wavelength (n.) One word.
we Don’t use first person; rewrite in terms of the reader or the product.
Correct: For best results, your Macintosh should have at least
8 MB of RAM.
Acceptable: It is recommended that your Macintosh have at least
8 MB of RAM.
Incorrect: We recommend that your Macintosh have at least
8 MB of RAM.
See also recommend.
Web Short form of World Wide Web. Note initial cap. See also World Wide Web.
You use Internet Explorer to connect to the Web.
Web address You use a Web address (usually expressed as a URL) to connect to
a Web page. Don’t break a Web address when you refer to the address in text; set
the address on a separate line if the address is very long. Don’t use Web address
(which applies to a Web page) when you mean Internet address (which can apply
to many locations, such as individual e-mail accounts, Web pages, and so on). See
also Internet address; URL; Web page.
Web page A self-contained document that can be viewed by using a Web
address. A single Web site can contain many Web pages. You connect to (or go to) a
page; you are then at that page. Text, graphics, and links, however, are on the
page. Don’t use Web site and Web page interchangeably. See also home page;
Web address; Web site.
Web site Refers to a collection of Web pages stored in a particular location. The
Web site may be organized into several parts or sections, each of which may
contain more than one page. Use part or section to refer to such an entity. Use
page to refer to a single Web page. Use site to refer to the entire collection. You
can browse, visit, or go to a Web site, but don’t use such phrases as point your
browser at the Web site and surf the Web site. See also home page; Web page.
Welcome to Mac OS message Not box or screen.
102
Style and Usage
well-behaved Don’t use to describe software; use compatible, wellconstructed, and the like.
which Use only to introduce an unrestrictive clause; clauses beginning with
which are always set off with commas. Compare that.
Correct: The largest house in town, which Jack’s sister built, is also the
newest. (There is only one largest house; the phrase which Jack’s sister
built, although it provides more information, does not restrict [narrow
the meaning of] the subject of the sentence.)
Correct: This is the house that Jack built. (There are many houses; the
phrase that Jack built restricts the subject of the sentence to one
house.)
whir Not whirr. But whirring.
The disk drive whirs; in a moment you see the opening display on
the screen.
who, whom Who should always be used as the subject of a verb or as a subject
complement. Whom should always be used as the object of a verb or preposition.
Who is the new interface director?
This manual is intended for the person who manages the network.
Be selective about the people to whom you give network access.
wide area network (WAN) Three words. Spell out on first occurrence; thereafter,
OK to use the abbreviation.
windoid Don’t use; use miniwindow.
window When an icon is opened, what appears on the screen is called a window,
not an open window. Inactive windows or objects are in back of or behind active
windows. Compare miniwindow.
window titles When referring to a window by name, use the exact words in the
title bar of the window (the Netscape Mail window, the window called About Mac
OS 8). Lowercase window (unless it’s capitalized in the title bar).
window zooming Note lowercase. No hyphen.
word processing (n.), word-processing (adj.) Note hyphenation of adjective.
words as words Italicize a word when it is used as a word. In text that is read
only on the screen, you can use quotation marks instead of italics. Use an
apostrophe and an s to form the plural, but don’t italicize the apostrophe or the s.
He had too many and ’s in the sentence.
word wrap Not wraparound or word wraparound. In manuals written for new
users, however, you may want to mention the term wraparound or include it in
your glossary because users may see it elsewhere.
workstation (n., adj.) One word. Don’t use when referring to a desktop
computer. OK to use when discussing network administration.
Style and Usage
103
World Wide Web Note capitalization. No hyphen. Web is an acceptable short
form after first occurrence. Don’t abbreviate as WWW.
wraparound (n.) Don’t use; use word wrap.
write-protect (v., adj.), write-protected (adj., pred. adj.), write-protection (n.)
Hyphenated in all forms.
You use the write-protect tab to write-protect a disk.
When a disk is write-protected, it can’t be changed.
Sometimes it’s necessary to remove the write-protection from a disk.
Compare copy-protect, copy-protected, copy-protection.
WWW Don’t use as an abbreviation for World Wide Web. Use Web instead.
x When used as a place holder for replaceable numbers, x is lowercase and
plain style.
$02xx (represents a range of Memory Manager errors)
Don’t use x ’s as place holders in numbers representing microprocessors.
Incorrect: 68xxx microprocessor
Correct: 68000-family microprocessor
XON/XOFF All caps. Refers to the handshake.
Y-adapter Note capitalization and hyphen.
zero character OK for the ASCII character $30. Don’t confuse with null character
($00).
zeros Not zeroes.
zip code Note lowercase.
Zip disk, Zip drive Note capitalization. Don’t call a Zip disk a cartridge.
zoom box Two words. Note lowercase.
104
Style and Usage
Appendix A
Technical Notation
T
his appendix gives special style and usage rules that apply largely or
exclusively to technical documentation. (These rules are also included by topic in
the main body of this guide.)
105
General
considerations
Code
When writing about a particular programming language, be careful to follow the
capitalization style of that language.
Be sure to explain in the preface how your book uses capitalization and
typography. If you use special text elements, such as tag boxes, incidental boxes,
or marginal glosses, it’s usually a good idea to explain your conventions for
these elements as well.
Use computer voice for code.
If the language you’re working with has a standard style of indentation, use it. If it
doesn’t have such a style, develop a logical method of your own and use it
consistently.
WHILE i<63 DO
BEGIN
IF odd(i) THEN z := z*w
ELSE z := y
END
Develop a method of spacing around punctuation and use it consistently. It’s
often best to use “English-style” spacing because it’s easy to remember and to
stick with.
(height, width: extended; quo: integer);
PageSize = 1024
Syntax descriptions
Use computer voice for literals (parts of the language, values, and so on), italic
regular text font for metasymbols (artificial terms that have meaning only in your
book and are to be replaced by a value or symbol), and plain style regular text
font for brackets that enclose something that’s optional. Pay close attention to
punctuation.
Read ([file, ] var)
Use a hyphen or an embedded cap to connect two words that act as a single
metasymbol.
Correct: source-file or sourceFile
Incorrect: sourcefile or source_file
Be consistent when naming metasymbols; for example, don’t alternate between
commands and command-list.
106
Appendix A: Technical Notation
Computer voice
in text
Most technical manuals use computer voice for computer-language elements in
text. Whether to use computer voice in text for other documents is a matter of
judgment.
Use computer voice for all text fragments that the reader should construe as
expressions in a programming language.
You may choose to use computer voice for the names of files, volumes, directories,
and libraries, especially in reference books for languages and development
systems where the filenames are names of pieces of code.
StandardCRuntime.o library
MainProg.c file
Such names are a special case because they are not part of executable code.
In general, don’t use a routine name as a verb.
Correct: Run ls on both directories.
Incorrect: ls both directories.
Correct: Change to the root directory.
Incorrect: cd to the root directory.
Avoid mixing fonts within a single word. Rewrite to avoid forming the plural of a
word in computer voice.
Correct: values of type integer
Incorrect: integers
Punctuation following a word or phrase in computer voice is in regular text font,
not in computer voice, unless the punctuation mark is part of the computerlanguage element represented.
NAN(004), nan(4), and NaN are examples of acceptable input.
Appendix A: Technical Notation
107
Metasymbols
in text
In running text, use italic regular text font when referring to a metasymbol (that
is, an artificial term that has meaning only in your manual and is to be replaced by
a value or symbol), and spell out the metasymbol just as it would appear in a
syntax description. Use plain style when using the name of a metasymbol as
ordinary prose.
Correct: Replace volume-name with a name of up to 12 characters.
Correct: The volume name may have up to 12 characters.
Incorrect: The volume-name may have up to 12 characters.
In manuals, do not use foo, bar, baz, or frobozz to represent hierarchical or
ordered metasymbols in code examples; use metasymbols that suggest the kind
of item that the programmer might fill in.
TObject.FirstMethod
TObject.SecondMethod
108
Appendix A: Technical Notation
Appendix B
Units of Measure
T
his appendix lists units of measure likely to occur in a computer manual. For
each unit, both the full term and the abbreviation are given, along with the
quantity for which the unit is used.
109
Guidelines
In user documentation, spell out all units of measure at first occurrence, whether
in text, tables, or technical specifications. Repeat the spelled-out version in new
sections and chapters if the abbreviation is obscure and if the level of audience
requires it.
Always spell out English units of measure in text (for example, 5.25-inch keyboard).
It’s OK to abbreviate them in tables and technical specifications (keyboard length:
5.25 in.).
It’s OK to abbreviate metric units after first occurrence, except for the unit meter.
(For example, the containment unit holds 45 ml of liquid but the mouse cable is 40
meters long.)
Abbreviations for English units are followed by a period. Abbreviations for metric
units are not.
In general, units of measure derived from a proper name are not capitalized when
spelled out, but their abbreviations are capitalized. (For example, joule is
abbreviated J.)
Use the same abbreviation for singular and plural forms, except for abbreviations
incorporating the word bit or byte, as in Kbytes or Gbits.
Use a space between a number and a unit of measure or its abbreviation, except
for the abbreviation K (kilobit), which is closed up with the numeral (84K).
Another exception is the degree symbol, which is closed up with the numeral and
followed by a space and the letter F, C, or K (451° F).
When using a spelled-out unit of measure in a compound adjective, hyphenate
the compound (45-inch floppy disk). When using a metric measurement, do not
hyphenate (20 nA battery).
In the table “Names and abbreviations for units of measure” on the next page,
when an abbreviation includes a nonalphanumeric character, the keystrokes that
generate the character are included in brackets after the abbreviation.
110
Appendix B: Units of Measure
m Table 2
Names and abbreviations for units of measure
________________________________________________________________________________________________________________
Unit
Abbreviation
Quantity
ampere
ampere-hour
ampere-second. See coulomb
amperes per meter
amperes per volt. See siemens
angstrom (10-10 meters)
attoampere (10-18 amperes)
baud (signal events per second)
bel (10 decibels)
bits per second
calorie (thermochemical calorie)
candela (or candle)
A or amp
Ah
electric current
rate of delivery of electricity
A/m
magnetic field strength
Å [Option-Shift-A]
aA
baud
B
bps
cal or C
cd [with metric
units] or cd.
[with English
units]
cd./sq. in.
cd/m2
cm
cpi
cps
C
optical wavelength
electric current
speed of data transmission
sound intensity
speed of data transmission
heat
luminous intensity
________________________________________________________________________________________________________________
candela per square inch
candela per square meter
centimeter
characters per inch
characters per second
coulomb (ampere-second)
coulombs per volt. See farad
cubic centimeter
cubic feet per minute
cubic feet per second
cubic foot
cubic inch
cubic meter
cubic meters per second
cubic yard
cycle
cycles per second. See hertz
decibel (0.10 bels)
degree
degree Celsius
degree Fahrenheit
degree Kelvin. See kelvin
degree Rankine
dots per inch
dyne
luminance
luminance
length
letter spacing (in type)
printing speed (on nonlaser printers)
electric charge
cm3
cu. ft./min.
cu. ft./sec.
cu. ft.
cu. in.
m3
m3 /s
cu. yd.
c
volume
change in volume over time
change in volume over time
volume
volume
volume
change in volume over time
volume
complete execution of a periodically
repeated phenomenon
dB
° [Option-Shift-8]
° C [Option-Shift-8]
° F [Option-Shift-8]
sound intensity
angular measure
temperature
temperature
° R [Option-Shift-8]
dpi
dyn
temperature
resolution
force
(continued)
Appendix B: Units of Measure
111
m Table 2 (continued)
_________________________________________________________________________________________________________________
Unit
Abbreviation
Quantity
electromotive force
emf
electron volt
erg
farad (coulombs per volt)
feet per minute
feet per second
feet per second squared
foot
gallon
gauss
gigabit
gigabyte
gigaelectron-volt (109
electron volts)
gigahertz (109 hertz)
gilbert
gram
grams per cubic centimeter
henry
hertz (cycles per second)
horsepower
hour
eV
erg
F
ft./min.
ft./sec.
ft./sq. sec.
ft.
gal.
G
Gbit
GB
GeV
energy derived from electrical source
per unit quantity of electricity
energy
work
capacitance
velocity
velocity
acceleration
length
volume
magnetic induction
computer memory
computer memory
energy
_________________________________________________________________________________________________________________
inch
inches per second
joule (kilogram-meter)
joules per second. See watt
kelvin
kilobit
kilobits per second
kilobyte
kilobytes per second
kilogauss (103 gauss)
kilogram (103 grams)
kilogram-meter. See joule
kilogram-meters per second
squared. See newton
kilograms per cubic meter
kilohertz (103 hertz)
kilohm (103 ohms)
kilometer (103 meters)
GHz
Gb
g
g/cm3
H
Hz
HP
h [with metric units]
or hr. [with English
units]
in.
in./sec.
J
frequency
magnetomotive force
mass, weight
density
inductance
frequency
power
time
K
Kbit
Kbps
K or KB
KB/sec.
kG
kg
temperature
computer memory
speed of data transmission
computer memory
speed of data transmission
magnetic induction
mass, weight
kg/m3
kHz
kΩ [Option-Z]
km
density
frequency
electric resistance
length, distance
length
velocity
energy
(continued)
112
Appendix B: Units of Measure
m Table 2 (continued)
_________________________________________________________________________________________________________________
Unit
Abbreviation
Quantity
kilometers per hour
kilovolt (103 volts)
kilovolt-ampere. See kilowatt
kilowatt (kilovolt-ampere)
kilowatt-hour
kph or KPH
kV
velocity
electric potential
kW
kWh
lines per inch
liter
liters per second
lumen
lumens per square
centimeter. See phot
lux
maxwell (10-8 webers)
megabit
megabits per second
megabyte
megabytes per second
megaelectron-volt (106
electron volts)
megahertz (106 hertz)
megohm (106 ohms)
meter
meters per second
meters per second squared
microampere (10-6 amperes)
microfarad (10-6 farads)
microgram (10-6 grams)
microhenry (10-6 henrys)
microliter (10-6 liters)
micron
(10-6 meters)
mil (10-3 inches)
mile
miles per hour
milliampere (10-3 amperes)
milligram (10-3 grams)
millihenry (10-3 henrys)
milliliter (10-3 liters)
millimeter (10-3 meters)
millimicron. See nanometer
million instructions per second
millisecond (10-3 seconds)
millivolt (10-3 volts)
milliwatt (10-3 watts)
minute
lpi
l
l/s
lm
power
energy (usually electric power
consumption)
resolution
volume
change in volume over time
flux of light
lx
Mx
Mbit
Mbps
MB
MB/sec.
MeV
illumination
magnetic flux
computer memory
speed of data transmission
computer memory
speed of data transmission
energy
MHz
MΩ [Option-Z]
m
m/s
m/s2
µA [Option-M]
µF [Option-M]
µg [Option-M]
µH [Option-M]
µl [Option-M]
µ [Option-M]
frequency
electric resistance
length, distance
velocity
acceleration
electric current
capacitance
mass, weight
inductance
volume
length
mil
mi. [except in mph]
mph or MPH
mA
mg
mH
ml
mm
length
length, distance
velocity
electric current
mass, weight
inductance
volume
length
MIPS
ms
mV
mW
min.
processor speed
time
electric potential
power
time
_________________________________________________________________________________________________________________
(continued)
Appendix B: Units of Measure
113
m Table 2 (continued)
_________________________________________________________________________________________________________________
Unit
Abbreviation
Quantity
month
nanoampere (10-9 amperes)
nanofarad (10-9 farads)
nanometer (10-9 meters)
nanosecond (10-9 seconds)
newton (kilogram-meters per
second squared)
newtons per square meter. See pascal
oersted
ohm
ounce
pascal (newtons per square meter)
phot (lumens per square centimeter)
picofarad (10-12 farads)
picowatt (10-12 watts)
pound
poundal
radian
radians per second
radians per second squared
revolutions per minute
second
mo.
nA
nF
nm
ns
N
time
electric current
capacitance
length
time
force
Oe
Ω [Option-Z]
oz.
Pa
ph
pF
pW
lb.
pdl.
rad or radian
rad/s
rad/s2
rpm
s [with metric units]
or sec. [with English
units]
S
sq. ft.
sq. in.
m2
sq. mi.
sq. yd.
T
tn. or ton
V
Vpp
Vrms
magnetic intensity
electric resistance
volume, weight
pressure
illumination
capacitance
power
mass, weight
force
angular measure
angular velocity
angular acceleration
angular velocity
time
conductance
area
area
area
area
area
magnetic flux density
mass, weight
electric potential
electric potential
electric potential
W
Wh
Wb
power
energy
magnetic flux
yd.
yr.
length, distance
time
_________________________________________________________________________________________________________________
siemens (amperes per volt)
square foot
square inch
square meter
square mile
square yard
tesla (webers per square meter)
ton
volt
volts (point-to-point)
volts (root mean square)
volt-ampere. See watt
watt (joules per second)
watt-hour
weber
webers per square meter. See tesla
yard
year
114
Appendix B: Units of Measure
Appendix C
How to Write Balloons
T
his appendix provides guidelines for writing clear, concise balloons, using
a style that’s familiar to users.
For additional information on creating balloons, refer to the BalloonWriter User’s
Guide and the “Help Manager” chapter in Inside Macintosh: More Macintosh
Toolbox. Design guidelines for your programs are available in the book Macintosh
Human Interface Guidelines.
115
What Balloon Help
can and can’t do
Balloons are onscreen descriptions of items. The balloon for an item appears
when the user moves the pointer to an item. This is a powerful method of
providing information, because the user knows exactly what the text is referring
to. But the method has some limitations. There are some kinds of information that
balloons cannot display effectively.
m Balloon Help can show users what they will accomplish by using the
objects on their screen, including menu commands, dialog boxes, and tool
palettes.
m Balloon Help can help experienced Macintosh users who prefer to learn a
program by using it, rather than by reading a manual.
m Balloon Help can’t help a user who doesn’t know what he or she wants
to do, or a user who doesn’t know where to look. (Any more than a
dictionary can help someone spell a word when they don’t know what letter it
begins with.)
m Balloon Help can’t teach your program by itself. It can’t substitute for taskoriented paper or electronic documentation or training.
m Balloon Help can’t teach novice Macintosh users the concepts they need
to know in order to use the Macintosh.
Balloon Help works best when you keep your audience in mind as you write. Ask
yourself these questions when you are planning balloons for your program:
m What people will be using your program?
m What aspects of your program are users not familiar with?
m What terminology are your users likely to know?
Unless your application program has a specialized audience, it’s best to write for
users who already know something about using the Macintosh (although they
may not be experts) but who don’t know much about your program.
116
Appendix C: How to Write Balloons
General guidelines
for writing balloons
These guidelines are presented as general rules, followed by explanations and
examples. Each guideline includes one or more examples. For each example, an
illustration presents an effective way to word the balloon and a table shows you
the effective wording, a less effective wording, and an explanation of the
difference.
Many of the example balloons are written for fictional application programs called
Widget Maker and Animals.
First describe what the user
will accomplish
What the user wants most to know should come first in the balloon. The user
wants to know what task he or she will accomplish by using the item.
For menu commands, the best way to accomplish this is usually to begin the
balloon with a verb describing what the menu command does. For other interface
elements, a good construction is “To [perform action], click this [name of item].”
(For more information, see “Recommended Wording for Specific Types of
Balloons.”)
After you’ve described what the user will accomplish by using the item the
balloon points to, then, if you wish, you can describe how the item works, or
other things the user might want to know about the item.
Appendix C: How to Write Balloons
117
Balloon for a New command
This
Opens a new document. The
document has the name “untitled.”
Not this
Why
This is a menu command. Choose this The user most wants to know what
command to open a new document. he or she will accomplish by
choosing the command.
Balloon for a Print button
This
To print the document with the
options you’ve chosen, click this
button.
118
Not this
After you’ve selected options, click
this button to print your document.
Appendix C: How to Write Balloons
Why
The user most wants to know what
he or she will accomplish (printing).
Other things should be described
later in the balloon.
Use the fewest words possible
Users are most likely to read and understand your balloons if you use the fewest
words possible. Keep sentences short. Present only one concept per sentence.
Present only concepts that are directly related to the item in question.
If your balloons will be translated into another language, you have another
reason to keep balloons short—translated text is often 20 to 30 percent longer
than English text. (See “Guidelines for Balloons That Will Be Translated,” later in
this section.)
Balloon for a New command
This
Opens a new widget document. The
new document has the name
“untitled.”
Not this
This menu command lets you open a
new widget document. The new
document has the name “untitled.”
or
A new widget document is opened
when you choose this menu
command. The new document has
the name “untitled.”
or
Opens a new widget document that
includes standard widget-designing
controls. The new document has the
name “untitled.”
Appendix C: How to Write Balloons
Why
The user already knows it’s a menu
command.
“Lets you” doesn’t tell the user
anything. Everything in the program
lets you do something.
Uses more words than necessary;
uses passive voice.
The balloon for the Open command is
not an appropriate place to discuss
the widget-designing controls.
119
Write separate balloons
for checked, selected,
or dimmed items
Whenever possible, write a separate balloon for each condition that a menu item,
button, tool, or checkbox might be in. (This might require special programming.)
Conditions include the following:
m Menu items: available, dimmed, checked (in rare cases a menu item might have
a diamond)
m Radio buttons or checkboxes: selected, unselected, dimmed
m Buttons in a dialog box: plain, outlined, dimmed
The beginning of the balloon should explain what the item usually does. The end
of the balloon should describe the special condition (why it is checked or
dimmed).
If there are many reasons why an item might be dimmed (or in some other special
state), don’t name them all. Describe one or two of the most likely reasons.
Whenever possible, use the same wording for the various balloons belonging to a
single item. Don’t vary the wording unnecessarily.
However, when describing an item that’s not available, don’t use the “To [perform
action], click this [item]” construction, because the user can’t click an item that’s
not available.
Use “not available” to describe a dimmed menu item or button. Use “dimmed” to
describe an open icon. (Additional wording guidelines appear in “Guidelines for
Phrasing Inside Balloons,” later in this appendix.)
120
Appendix C: How to Write Balloons
Balloon for a dimmed New command
This
Not this
Opens a new document. Not available Opens a new document. Grayed
because a document is already open. because a document is already open.
or
Opens a new document. Not available
because a document is already open,
there is not enough memory, a dialog
box is on the screen, or a desk
accessory is open.
Why
It is more helpful to the user to know
what the grayed appearance means.
Too many explanations—might be
confusing to the user. It’s best to
put only the most likely explanation
in the balloon.
Balloon for a dimmed radio button
This
Not this
Lines up curlicues at the left margin
To line up curlicues at the left margin
of the widget. Not available because a of the widget, click this button. Not
round widget is selected.
available because a round widget is
selected.
Appendix C: How to Write Balloons
Why
The “to [perform action], click this
[item]” construction isn’t
appropriate when an item isn’t
available, because the user can’t click
the item.
121
Write extra balloons for hidden
conditions
The more specific your balloons are, the easier it is for the user to figure out how
your application program works. It’s especially important to write a specific
balloon for a situation the user might find difficult to figure out. For example, if a
selection in a Preferences dialog box causes some menu commands to be dimmed,
a special balloon should appear when that selection is on.
Regular balloon for a dimmed command
Balloon for a command that’s dimmed because of a
selection elsewhere
This
Regular balloon
Opens a new document. Not available
because a document is already open.
Not this
Single balloon for all cases
Opens a new document. Not available
because a document is already open,
a dialog box is on your screen, the
Special balloon
program is out of memory, a desk
Opens a new document. Not available accessory is open, or Modify
because Modify Documents Only is
Documents Only is checked in the
checked in the Preferences dialog
Preferences dialog box.
box.
122
Appendix C: How to Write Balloons
Why
The single balloon contains too
many explanations. The user may not
read the whole list of items on the
screen.
It’s best to provide the most likely
possibility in the regular balloon,
and the obscure one in another
balloon that appears when the
option is checked.
Don’t name an item unless the
name helps the user
Many of the items on screen don’t need names. An item needs a name only if the
name helps the user remember how to use the program. The following items are
likely to need names:
m icons that don’t already have names on the screen
m tools in a tool palette
m controls on a ruler
m controls in a paint program
m icons in the Finder whose names can be changed
Some items need a generic name, indicating how they are used, but they don’t
need a specific name.
Before you name something in a balloon, ask yourself these questions:
m Will this name help the user remember how to use the program?
m Does this item need to have a specific name? Or would a generic name do?
m Is the item already named on the screen? If so, it’s not necessary to name it in a
balloon.
If you decide to name an item, make sure that the name you use in the balloon
matches the name used in other documentation.
Balloon for a selection handle
This
To change the size of the selected
item, drag this handle.
Not this
Selection handle
To change the size of the selected
item, drag this handle.
Appendix C: How to Write Balloons
Why
The user doesn’t need to know the
term selection handle in order to use
the object. The generic name handle
is sufficient.
123
Balloon for a paint tool
This
Paint Bucket
Not this
To fill an area with a pattern, click this
icon and then click the area you want
To fill an area with a pattern, click this to fill.
icon, then click the area you want to
fill.
124
Appendix C: How to Write Balloons
Why
It’s helpful to the user to know the
name of the icon, because that helps
him or her remember how to use the
tool.
Don’t name an item that’s
already named on screen
It’s best to keep balloons as short as possible, and one way to avoid extra words
is to avoid naming things in balloons if they’re already named on screen.
Finder icons are an exception, because the user can rename Finder icons. For
example, you may want to include your application program’s name in the balloon
for its icon.
Balloon for a button in a dialog box
This
To discard the changes you’ve made
to the active document, click this
button.
Not this
To discard the changes you’ve made
to the active document, click this
“Don’t Save” button.
Appendix C: How to Write Balloons
Why
The words “Don’t Save” are already
on the screen, so it’s not necessary
to use them in the balloon.
125
Use active voice
Active voice usually uses fewer words and is easier to read than passive voice.
Balloon for a size box
This
To change the height and width of
the window, drag this box.
126
Not this
Why
The window is made bigger or smaller Passive voice uses more words and is
by dragging this box.
more difficult to read.
or
This size box is used to resize the
window. The box is dragged to resize
the window.
Appendix C: How to Write Balloons
You can use a sentence
fragment beginning
with a verb
It’s OK to use sentence fragments in a balloon—in other words, it’s OK to leave
out the subject of the sentence if the item is named on screen. Sentence
fragments make balloons shorter, and the thing that the user really wants to
know (what the item does) comes first in the balloon.
Use sentence fragments with:
m menu commands
m checkboxes and radio buttons that are not available
m radio buttons that are selected
Balloon for a Save command
This
Saves changes to the active
document.
Not this
The Save command saves changes to
the active document.
Why
The user already knows it’s a
command, and “Save” is already on
the screen.
Balloon for a dimmed Bold style checkbox
This
Not this
Applies this style to the selected text. The Bold checkbox applies the Bold
Not available because no text is
style to the selected text. Not
selected.
available because no text is selected.
or
To apply the Bold style to the
selected text, click this box. Not
available because no text is selected.
Appendix C: How to Write Balloons
Why
Beginning the balloon with a verb is
appropriate because “Bold” is
already on the screen. Also, it is not
necessary to use the name
“checkbox” here.
It’s not appropriate to use the “To
[perform action], click this [item]”
construction if the user can’t perform
an action right now (because the
item is not available).
127
Define unfamiliar words
When you’re describing a menu item or a button, try to use a word that’s different
from the one that appears on screen. This helps users who aren’t sure what the
item means.
Balloon for an Undo command
This
Cancels your last action.
Not this
Undoes your last action.
Why
It’s better to use “Cancels,” because
that explains what the Undo
command does.
Balloon for a Paste command
This
Not this
Inserts the contents of the Clipboard Pastes the contents of the Clipboard
into the document.
into the document.
128
Appendix C: How to Write Balloons
Why
It’s better to use “Inserts,” to explain
what the Paste command does.
Describe only one way of
doing something
If there is more than one way of doing something, only mention one way in the
main body of the balloon.
Describe the method that involves the item the user is pointing at. In other
words, if the user is pointing at a button, the balloon should instruct the user
how to use the button, not how to use a keyboard shortcut for that button.
If there is more than one method involving the item the user is pointing at,
describe the method that’s simplest to describe and understand.
Balloon for a default Save button
This
To save the changes you have made
to the settings in this dialog box,
click this button.
Not this
To save the changes you have made
to these settings, click this button or
press the Return key.
or
To save the changes you have made
to these settings, press the Return
key.
Appendix C: How to Write Balloons
Why
The extra information makes the
sentence harder to understand.
The balloon should describe how to
use the item the user is pointing at
(in this case, the button).
129
Go easy on hints
If there are just a few interesting features in your program that would be difficult
to discover, then it’s appropriate to use balloons to call those features to users’
attention.
But if you want to give a hint or shortcut in a balloon, ask yourself these
questions:
m Is the balloon reasonably short, even with the hint?
m How often will users need the information? If it’s a very obscure feature that
few people would need, it probably doesn’t belong in the balloon.
m Are hints and shortcuts available somewhere else, for example in a “shortcuts”
dialog box or a quick-reference card? Not all users will look at balloons. If your
program includes many shortcuts and tricks, be sure to list them in other
documentation as well.
m Does the need for hints indicate the need for a different design? If there are a
lot of hidden shortcuts and features in your program, then the program may need
to be redesigned to make these features more easily accessible to users.
Put the hint or shortcut on a separate line at the end of the balloon.
Balloon for setting a clock
This
To set the time, click a number, then
click the arrows that appear.
Hint: you can also type a new
number.
130
Not this
To set the time, click a number, then
click the arrows that appear or type
to insert a new number.
Appendix C: How to Write Balloons
Why
The hint is short and simple enough
to fit into the balloon, but it’s easier
for the user to comprehend two
simple sentences than one sentence
with several different options.
Describe only the item the
user is pointing to
In a dialog box or a control panel, in most cases, you should try to describe only
the item the balloon is pointing to. It may be tempting to discuss the
relationships among items, but if you overdo it, the balloons can become complex
and difficult to read. Remember that the user can point at other items to find out
what they are.
Direction indicators (“to the left,” “at bottom,” “below”) can be difficult to follow,
especially if there is more than one direction indicator in the balloon. This is
another reason to avoid describing other items.
Balloon for Print button
This
To print the document with the
options you’ve chosen, click this
button.
Not this
To print the number of copies of the
document that you’ve selected to the
left, using the printer named at the
top of this dialog box, click this
button.
Why
The longer balloon is more difficult to
read. Discussing other options is
not necessary in this balloon—the
options are discussed in other
balloons. Multiple direction
indicators (“to the left,” “at top”) are
difficult to understand.
It’s OK to refer to other items and use direction indicators when it is necessary,
for example, when the user’s choices for an item are limited because of a selection
elsewhere in a dialog box.
Appendix C: How to Write Balloons
131
Balloon for a checkbox that’s dimmed because of a
selection elsewhere
Describe multiple-step
procedures only if they are
simple to remember
Balloons are not usually appropriate for describing multiple-step procedures,
because a balloon does not stay on the screen while the user performs the
various steps. The user may begin a procedure described in a balloon, and then
become confused when the information disappears.
It’s OK to describe a very simple two-step procedure in a balloon. For example, it’s
OK to describe two steps in a balloon for a tool in a tools palette.
132
Appendix C: How to Write Balloons
Balloon for a tool in a palette
Guidelines for balloons that
will be translated
If your balloons will be translated, don’t append subphrases to a balloon when
an item is in a special condition. (For example, a Finder icon balloon contains the
following subphrase when an icon is open: “The icon is dimmed because the disk
is open.”) Write separate balloons for the special conditions instead. The grammar
of a foreign language may change based on the context, so you can’t assume that
the same phrase will fit into several different sentences.
Expect the text to expand 20 to 30 percent after translation. In order to keep
foreign-language balloons to 255 characters, limit the English balloons to
approximately 180 characters.
Appendix C: How to Write Balloons
133
Recommended
wording for specific
types of balloons
Buttons with words
It’s easiest for the user to read balloons if similar balloons use similar wording.
Unnecessary variations in wording are distracting. Here are Apple’s choices for
phrasing in Finder balloons. If you use similar phrasing in your balloons, users
are likely to find your balloons “familiar” and easier to understand.
For buttons that appear in dialog boxes, use the “To [perform action], click this
button” construction.
Balloon for an Apply button
Balloon for a Don’t Save button
134
Appendix C: How to Write Balloons
Menu titles
For menu bar menus, give the title of the menu and then describe what kinds of
commands are in the menu. You give the title of the menu because some menus
on the menu bar are icons, not words.
Balloon for a menu in a menu bar
For pop-up menus, describe what to do with the menu. Don’t give the
menu a name.
Balloon for a pop-up menu
Appendix C: How to Write Balloons
135
Menu items
Don’t name the menu item. Begin with a verb describing what happens when you
choose the item.
Balloon for a Font menu item
Balloon for a menu command
136
Appendix C: How to Write Balloons
Menu items that display
dialog boxes
It is often not necessary to say in the balloon that a menu item displays a dialog
box. The fact that a menu item displays a dialog box may not be the thing the user
most wants to know. The user wants to know what choosing the menu item
ultimately accomplishes.
Balloon for a menu command that displays a dialog box
Items that aren’t available
After you explain what the item usually does, explain why it is dimmed or
otherwise unavailable, beginning with the phrase “Not available because...”
Balloon for a dimmed menu command
If there are a great many conditions that might result in an item’s not being
available, don’t list them all. List one or two of the most likely conditions only, or
create separate balloons for each condition, especially obscure ones. (For more
guidelines, see “Radio Buttons” and “Checkboxes,” later in this section. Also see
“General Guidelines for Writing Balloons,” earlier in this appendix. )
Appendix C: How to Write Balloons
137
Radio buttons
It’s best to provide separate balloons for selected, unselected, and dimmed radio
buttons, but in some cases this might require special programming, or the
program might not be able to tell the condition of the button. If that’s the case,
then describe what the button does when selected, beginning with a verb.
Balloon for a radio button in any state
For selected radio buttons, describe what the selected button does, beginning
with a verb. At the end of the balloon, say that the button is selected.
Balloon for a selected radio button
For an unselected radio button, describe what happens when you select the
button.
Balloon for an unselected radio button
138
Appendix C: How to Write Balloons
For a button that’s not available, describe what the button does when selected,
using a sentence fragment beginning with a verb. Then explain why it is not
available.
Balloon for a radio button that’s not available
Checkboxes
For checkboxes, provide the following information:
m the current state of the system (what the system does now, given the options
that are selected or not selected)
m an explanation or description of the option provided by the checkbox (if
necessary)
m how to turn on/off the option
Do not describe the current state of the system if it’s obvious or if it would
involve saying merely “this option is not on.”
Do not provide an explanation of the option if your users don’t need one.
Balloon for a selected checkbox
This balloon describes the current state of system, provides an explanation of the
option, and describes how to turn off the option.
Appendix C: How to Write Balloons
139
Balloon for an unselected checkbox
The balloon does not describe the current state of the system (“The document is
not being displayed in the holographic projection area”), because it’s obvious. It
provides an explanation of the option and describes how to turn on the option.
More balloons for selected checkboxes
140
Appendix C: How to Write Balloons
More balloons for unselected checkboxes
In this case the current state is not described; it’s not necessary to say “The
selected curlicue does not contain Victorian design elements.”
The current state (“You see the animals without their habitat”) is not described,
because it’s obvious from the screen.
Appendix C: How to Write Balloons
141
Balloons for checkboxes that aren’t available
Describe what the box does when it’s selected, and then explain why it is not
available.
142
Appendix C: How to Write Balloons
Groups of buttons or
checkboxes
It’s OK to provide a single balloon for an entire group of radio buttons (although
this may require special programming). You can also provide a single balloon for a
group of checkboxes, if the checkboxes are closely related.
When providing one balloon for a group of options, describe first how to
implement the options, and then describe how you can tell whether an option
is selected.
Balloons for groups of radio buttons
Balloon for a group of checkboxes
Appendix C: How to Write Balloons
143
Tools in palettes
It’s a good idea to name tools, because the name of a tool is often a clue to its
use; it helps the user figure out what the tool is for.
After naming the tool, describe one or two likely ways to use it. Don’t describe
every shortcut or trick you can do with the modifier keys.
Balloons for design tools
144
Appendix C: How to Write Balloons
Window parts
Use Apple’s standard balloons for these. If your windows have non-standard
parts, use the general guidelines at the beginning of this document when writing
balloons. (See Macintosh Human Interface Guidelines for recommendations on
window design.)
Name only the parts of the window that it’s necessary for the user to know.
Dialog box on screen
When there is a dialog box on the screen, you can add the following wording to
the end of each balloon that refers to an unavailable item:
Not available because a dialog box is on the screen.
Icons
Apple provides standard balloons for icons. If you wish, you can provide your
own balloons for an application program and its associated special files (but not
for your program’s document icons).
Don’t describe how to open icons; you can assume Macintosh users know how.
Balloon for an application program icon
Balloon for a Preferences file icon
Appendix C: How to Write Balloons
145
Text entry areas
Use “here” to describe the area. You don’t have to describe standard Macintosh
editing procedures.
Balloon for a text box
146
Appendix C: How to Write Balloons
Guidelines for
phrasing inside
balloons
Apple writers use the following guidelines for wording inside balloons. It’s best
to follow these guidelines, because consistent wording is easier to read and
understand. (Just as consistent interfaces are easier to learn.)
This
display information about
Not this
display Info window
on the Clipboard
in the Clipboard
dialog box
dialog
click
not available
click on
dimmed, grayed
active
frontmost, current
Word or phrase
this
close the dialog box
Why
Avoids jargon, more meaningful to
the user. It’s better to describe what
a feature does than to mention its
name.
Preserves the metaphor. You don’t
put papers inside a real clipboard.
If you must use a name for
something, use its full name, not an
abbreviation.
“On” is unnecessary.
It’s more informative to the user if
you describe the state of the system,
rather than the appearance of the
system.
Apple style. In cases where
terminology is necessary, it’s best if
user sees consistent terminology in
all documentation.
Guideline
To avoid many occurrences of the word “this” in a
balloon, use “this” only when you’re referring to the
thing you’re manipulating with the mouse (for example,
button, menu item). Otherwise use “the” or “a.”
For example: “To save changes to the widget, click this
button.”
To avoid extra words, use this wording only in the
balloon for a Cancel button (“To close the dialog box
without saving any changes, click this button”).
In balloons for buttons that close dialog boxes and also
perform other actions, just mention the other action (“To
save the changes you made, click this button”).
Appendix C: How to Write Balloons
147
Appendix D
Newton Style Guide
N
ewton is not Macintosh. Much of the terminology used in Macintosh
documentation is not appropriate for Newton documentation. This appendix
describes terminology and style developed to describe Newton and the Newton
interface.
This appendix has three sections. The first section is a list of Newton terminology,
definitions, and usage guidelines. The second section is a list of computer
terminology that should not be used in Newton documentation if possible.
Substitute wordings are suggested. The third section contains suggestions for
keeping your Newton documentation as short as possible.
149
Newton terminology
AC adapter Note capitalization.
Action button The button shaped like an envelope that contains commands to
fax, print, beam, e-mail, delete, and duplicate.
align The process of tapping X’s on the screen to line up the screen and the pen.
application card Avoid PCMCIA card except as an explanation of the
preferred term.
appointment An item in the Calendar portion of the Date Book. Event is also OK,
especially in the phrase repeating event.
appointment slip What you get when you tap the appointment marker.
area, location A whole part of the Newton interface, such as the Notepad, Date
Book, Preferences, Extras Drawer, etc. Don’t use it to refer to a single item in one of
these areas (such as a note or card). For that, use item, or name the kind of item
(note or card).
arrow, arrow button Whenever possible use simply arrow (“Tap the arrow at the
bottom of the screen”).
Assist Drawer The box that opens when you tap Assist, which contains the Assist
slip and “How Do I?” help. Preferred to Assist slip.
Assist slip Can be used to describe what appears when you tap the Assist button.
But what appears when you tap Do is called a confirmation slip or a specific name
(such as print slip).
assistant The functionality in Newton that interprets and carries out requests.
Don’t use Intelligent Assistant. When discussing the assistant feature, use
assistant rather than Newton. (“Tap to see a list of tasks the assistant knows how
to do.”)
backup battery The round lithium battery.
bar short for separator bar (Notepad, To Do List). Don’t use to refer to the bar
marking the length of an appointment in the Date Book. That’s called an
appointment marker.
battery case Two words.
battery life, battery power Battery life refers to how long batteries themselves
last before they need to be replaced. Battery power refers to how long one battery
charge lasts. For the AAA batteries, they are simultaneous. For the battery pack,
they are different.
battery switch The switch you use when you replace batteries.
beam Avoid using beam as a noun. Use to beam information or to send
information or information when context allows it.
150
Appendix D: Newton Style Guide
blinking line Similar to the Macintosh insertion point in function, but don’t use
insertion point to describe it.
box Describes various Newton items that are smaller than the whole screen that
have their own X (except for the Extras Drawer, and cards in the Name File). Also
called slip.
button Anything that has a picture and that does something when you tap it.
Don’t use icon when describing Newton.
Calculator Note capitalization.
Calendar The appointment scheduling part of the Date Book.
calendar The monthly calendar at the corner of the Date Book (also called minicalendar).
card 1. A removable application card or storage card. 2. An item in the Name File.
card lever The lever you use to insert or remove an application or storage card.
Also called release lever.
card slot The place where an application or storage card goes.
checkbox A box that you tap to add or remove a checkmark. One word.
circle the item Describes the selecting technique where you draw a circle around
the item you want to select.
communication port Newton’s serial port.
confirmation slip What you get when you tap Do in the Assist Drawer.
correction keyboard Avoid; use simply keyboard.
darkened Describes a recognizer button that’s on.
Date Book What you get when you tap the Dates button. Has a Calendar and a
To Do List.
Dates button Note capitalization.
day note An event in the Date Book that does not have a specific time assigned to
it (such as a birthday). It appears at the top of the calendar page.
diamond 1. The control that you tap to see a list of choices. 2. A slider control
(such as in the contrast control feature).
dot Describes the Overview button (the dot between the two arrows). Don’t use
Overview dot.
down arrow Note lowercase.
draw the highlighting mark Describes how you select something.
e-mail Note hyphen. Mail is also OK.
enter Don’t use if you can use write instead. OK where a keyboard is likely to
be used.
Appendix D: Newton Style Guide
151
event, repeating event Appointment in the Date Book.
Extras Drawer Note capitalization.
Find box, Find slip Either is OK.
folder A subset of notes or address cards.
folder button The button on a note or address card that you use to categorize
items.
get Don’t use download.
handwriting, handwritten text Unrecognized writing. Compare text.
highlighting mark The heavy black line that you use to select something.
In Box
information slip A box that requests more information. Blanket descriptor for
various kinds of slips (confirmation slip is also OK when describing the Assist
feature). Use the specific name (print slip, routing slip) where possible.
item A single note, card, appointment, or to-do.
keyboard, onscreen keyboard Use keyboard wherever possible; onscreen
keyboard on first occurrence in section. Describe specific keyboard only if
necessary.
later notes, earlier notes Avoid this; use beginning and end or up and down
when describing the Notepad.
list of words Use to describe either Newton’s or the user’s list of words. Don’t
use vocabulary list or dictionary.
location, area A part of the Newton interface, such as the Notepad, Date Book,
Preferences, Extras Drawer, and so on. Don’t use for a specific item (such as a
single note or card).
locking tab Part of card slot.
mail Synonym for e-mail.
main batteries The AAA batteries or the rechargable battery pack.
marker The vertical line that marks the length of an item (appointment or to-do)
in the Date Book. Can be modified with the word appointment or activity.
message Text that appears in a box. Warning message is also OK. Don’t use alert
box or dialog box .
mini-calendar The monthly calendar in the Date Book that you manipulate to go
to another date (can also be called calendar).
misinterpret Use to describe what happens when Newton guesses the user’s
intentions incorrectly.
Name File Note capitalization.
152
Appendix D: Newton Style Guide
Names button Note capitalization.
Newton asks (for information) OK to use.
Newton OK not to use a modifier with Newton. (“Don’t get Newton wet.”)
note An item in the Notepad
Notepad The Notepad is always open underneath everything else.
object Avoid; use item.
onscreen keyboard Use keyboard wherever possible; onscreen keyboard on first
occurrence in section. Describe specific keyboard only where necessary.
on/off switch Power switch is also OK.
open Don’t use open to describe moving to different areas in Newton (except for
the Extras Drawer). Use go to or an equivalent phrase.
Out Box Note capitalization.
Overview button The dot between the arrows. Use simply dot if the context is
clear.
pen Use Newton pen on first occurrence. Don’t use stylus.
plastic card Describes the protective card that must be installed in the card slot
whenever an application or storage card is not being used.
power port Describes the place where you plug in a power adapter.
power switch On/off switch is also OK.
preferences area A section of the list you get when you tap Prefs in the Extras
Drawer. “Make sure ‘Receive Beams Automatically’ is turned on in the Beam
preferences area.” Shorten to area or preferences.
Prefs The name of the button in the Extras Drawer that takes you to the list of
preferences.
print slip The box you use to choose a printer and format.
priority diamond The black diamond that indicates the priority of an item in the
to-do list.
put [notes, cards] in folders Describes process of categorizing notes or cards.
recognize, recognition Describes Newton’s text recognition and shape
recognition features. Don’t use interpret.
recognizer buttons Describes the text and shape recognition buttons. Don’t
use interpreter buttons.
release lever Releases a card from card slot. Also called card lever.
repeating event A repeating appointment in the Date Book.
Appendix D: Newton Style Guide
153
request Something you ask the assistant to do.
request word A word that the assistant knows how to interpret.
reset button Preferred to reset switch.
routing slip General descriptor for print slips and fax slips.
screen Use only to describe Newton’s physical screen. Don’t use to describe
areas of Newton such as the Notepad.
scrub mark The W shape you make when erasing something. Don’t use scrubbing
gesture.
scrub, scrub out, scrub over Describes erasing writing or drawing. Don’t use
scribble, scribble out, erase, or delete.
selecting As on the Macintosh, describes marking an object such as text or a
drawing for modification.
selection box The box that appears after you circle something with the
highlighting mark. Use just box where possible.
separator bar The bar with information in it that separates items in the To Do List
and Notepad. Shorten to bar where possible.
shape recognizer The button you darken to clean up shapes; also the
functionality. Preferred to drawing recognizer.
slip Describes any box that requests information from the user. Must be used
with a modifier, for example, confirmation slip, print slip.
SRAM card Note no hyphenation. Note capitalization.
storage card Don’t use memory card. Avoid PCMCIA card except as an
explanation for the preferred term.
store information in Newton Note preposition.
store information on a storage card Note preposition.
tap the X Describes closing something. Don’t use tap X.
tap, tap on Describes touching the pen to the screen. Don’t use click. You tap
things to choose them or activate them.
task Describes something the assistant knows how to do. Request is preferable.
tell Newton Describes giving Newton information.
text Recognized handwriting.
text recognizer The button you darken to turn on handwriting recognition.
Time Zones An area in the Extras Drawer.
To Do List Note spacing and capitalization. Part of the Date Book.
154
Appendix D: Newton Style Guide
to-do item Describes a single item in the To Do List.
to-do list Use this hyphenation and capitalization when referring to the list that a
user creates on a specific day.
touch-sensitive screen Note hyphenation.
typed text Text that Newton has recognized or that has been entered with a
keyboard.
uncheck Describes removing a check from a checkbox to turn off an option.
underneath, on top of Describes positions of various areas. The Notepad is
always underneath everything else.
unselect by tapping outside the item Describes removing a selection box or mark
from something.
up arrow Note lowercase.
use the pen to Avoid describing actions in this way when discussing drawing,
writing, or tapping (except in tutorial materials). OK to refer to the pen when
discussing moving things.
write, write in, fill in Preferable to enter.
writing keyboard Don’t use; use keyboard.
X, the Always use the with X (“tap the X to close the Extras Drawer”).
zigzag Use to describe the scrub mark.
Appendix D: Newton Style Guide
155
Terminology not
to use
Avoid the following terminology when describing Newton. Use the substitute
word or phrase, or an equivalent, instead.
Don’t use
Use instead
alert box, dialog box
message, message box, warning message
click
tap
close box
the X
dialog box
message, box, slip (must use descriptor with slip)
dictionary
list of words
download, upload
get
drag
move
erase
scrub, scrub over, scrub out
icon
button
insertion point
blinking line
interpret
recognize (but misinterpret is OK)
memory card
storage card
menu
list
open
go to
overview list
list [of something]
pop-up menu
list
pull-down menu
list
radio button
button
scroll
move
stylus
pen, Newton pen (on first occurrence)
table of contents
list [of something]
vocabulary list
list of words
Avoid describing Apple’s Newton documentation by title. Instead, refer to “the
documentation that came with your Newton” or “Newton’s onscreen help.”
156
Appendix D: Newton Style Guide
Keep your manual
short
m Avoid lengthy introductions that describe the advantages of your product. This
information is more appropriate on the outside of the box. If you must include
a description, keep it to a page or less.
m Skip the preface for manuals that are less than approximately 50 pages in
length. Use the table of contents to communicate what information is available
in each section or chapter.
m Weave conceptual information into the detailed instructions. People don’t
remember conceptual information unless they are using it to do their work.
m Don’t provide a tutorial on how to use Newton. Assume that people know the
various elements of the Newton interface (for example, that tapping a diamond
brings up a list, or that tapping an X closes something) and know how to get
around in Newton. For slightly more complicated tasks such as handling
application cards, copying text to another area, and so on, refer users to “the
documentation that came with your Newton.”
Appendix D: Newton Style Guide
157
Appendix E
How to Write a Glossary
A
good glossary can enhance a manual’s usefulness to readers much as do
the table of contents and a good index. Here are some guidelines for preparing a
glossary.
v Note: Glossary, as used here, refers to an alphabetized list of terms with
definitions—not the collections of keywords used in Microsoft Word for
formatting a document. v
159
Audience
considerations
Know your audience
Keep in mind the needs of the people for whom you are writing. Follow the
guidelines in this section.
If your manual is intended for first-time computer users or first-time Apple product
users, you’ll probably have to include terms you might think of as having obvious
meanings—such as disk drive, 3.5-inch disk, System file, window, screen, menu,
start up, and command. Earlier user manuals can serve as guides when deciding
what to include; developmental editors can also make helpful suggestions.
Technical manuals needn’t assume computer illiteracy on the part of readers—you
may not have to define general computer terms like silicon or application
program. However, you should probably assume that some readers will be
ignorant of Apple terminology. Terms like language card, Finder, or IWM
(Integrated Woz Machine) should probably be in the glossary if your manual uses
them. Again, it depends on your audience; for example, the glossary of Inside
Macintosh, Volumes I–III, does not include Finder but does include File Manager.
Intermediate manuals or installation manuals for peripheral devices lie in a gray
area. Can you assume, for example, that the person buying a hard disk has already
learned how to use the computer? Perhaps not. But some hard disk buyers will be
highly advanced users. When deciding which terms to include, you should
probably err on the side of including terms that most readers might already know,
rather than leaving out those that some readers won’t know, insofar as the terms
belong in the manual’s context.
160
Appendix E: How to Write a Glossary
Make definitions explanatory as
well as correct
Make the context clear
Connect ordinary usage with
technical meaning
Give an example where appropriate; if possible, make that example specific to the
system about which you’re writing. Where helpful, refer to other glossary terms
for further information or contrast.
Is your definition general to all computers, specific to Apple computers, specific to
a particular device or system, or somewhere in between? If a term has two or more
meanings that are relevant (such as format, the noun referring to page
appearance, and format, the verb referring to the action performed on a blank
disk), provide all definitions.
Many ordinary English words have specific meanings with regard to computer
products. In manuals for first-time users, it’s helpful to show the connection
between the ordinary meaning of the word and its new, technical meaning. For
example, here’s a definition for open:
open: To make available. You open files or documents in order to work with
them. A file may not be read from or written to until it is open. In the desktop
interface, opening an icon causes a window with the contents of that icon to
come into view. You may then perform further actions in the window when it’s
active.
The initial definition of open, “to make available,” is one of the meanings given the
verb in The American Heritage Dictionary. It provides a conceptual link to the
reader.
Appendix E: How to Write a Glossary
161
Matters of form
Design
These guidelines tell how entries should be formatted and structured and what
conventions we follow in Apple manuals.
The appearance of your entries will vary with your book design. If you are working
in Microsoft Word,
The glossary macro sets up the entire Glossary section and page format for you,
including the opening, footers, and division break. See your design
documentation for specs and sample pages.
Format of an entry
The term to be defined is in boldface. Do not capitalize the term unless it is a
proper noun.
The definition, in plain text, starts with a capital letter and ends with a period. The
first clause of the definition is a sentence fragment. Other parallel phrases in the
definition may also be sentence fragments; otherwise, use complete sentences.
Alphabetization
Alphabetize entries letter by letter up to a punctuation mark; spaces do not
count. For example, controller comes before control panel. Numerical entries are
ordered as though they were spelled out. For example, 6502 comes between shell
and soft switch.
Where there are several similar numeric entries, however, such as 68000, 68020,
68851, and so on, order the entries numerically within the group. This is a change
to the previous rule; Apple III now comes after Apple II.
Parts of speech
Pronunciation
If the term is a verb, start the definition with an infinitive (“To make available”) and
not a gerund (“Making available”). If the term is an adjective, you may have to
start the definition with wording such as “Said of . . . ,” “Characteristic of . . . ,”
“Used to describe . . . ,” or some such. You may also use (n.), (v.), or (adj.) for
noun, verb, or adjective to distinguish the part of speech.
When defining acronyms or other terms with unusual or unclear pronunciation,
provide a key in this form:
ASCII: Acronym for American Standard Code for Information Interchange
(pronounced “ASK-ee”).
EBCDIC: Acronym for . . . (pronounced “EB-si-dik”).
leading: Pronounced “LED-ing”; the amount of blank vertical space
between. . . .
The pronunciation key is inside quotation marks; hyphens separate the syllables,
and all-caps indicates the stress.
162
Appendix E: How to Write a Glossary
Cross-references
Within your definition, use boldface for other terms in the glossary that you want
the reader to consult in relation to this definition. Use italics for terms that are
synonyms or antonyms but that don’t need to be looked up separately (or don’t
appear in your glossary). If you use a term that appears in the glossary but do
not want to draw particular attention to it, just use roman (plain text). Avoid
making entries look like this:
(Cluttered)
open: To make available. You open files or documents in order to work with
them. A file may not be read from or written to until it is open. In the desktop
interface, opening an icon causes a window with the contents of that icon to
come into view. You may then perform further actions in the window when it’s
active.
If you think cross-referencing is needed, it’s often better to do so this way, with
cross-references at the end:
(Better)
open: To make available. You open files or documents in order to work with
them. A file may not be read from or written to until it is open. In the desktop
interface, opening an icon causes a window with the contents of that icon to
come into view. You may then perform further actions in the window when it’s
active. Compare close. See also icon; window.
Important
Make sure all cross-referenced terms are in your glossary.
“See” means that the definition for a term is given elsewhere.
“See also” means that additional relevant information is given elsewhere.
“Compare” means that a contrasting or complementary term is defined elsewhere.
It isn’t necessary to say “Compare with. . . .” You may also use “Same as” and
“Opposite of” for synonyms and antonyms.
Appendix E: How to Write a Glossary
163
Multiple definitions
Each definition in a sequence is preceded by a number in parentheses followed by
a single space:
graphics: (1) Information presented in the form of. . . . (2) The display of
pictures. . . .
If the definitions are for different parts of speech, each one is preceded by the
part-of-speech abbreviation in parentheses with a period:
branch: (v.) To pass program control to a line or statement other than the
next in sequence. (n.) A statement that performs the act of branching. See also
conditional branch; unconditional branch.
More complexity is possible; consult a developmental editor, if necessary, when
dealing with complex entries.
Independence
164
Your glossary should stand alone. Don’t include references to text sections or to
other publications.
Appendix E: How to Write a Glossary
Assembling the
glossary
First, decide which terms you need to include and define for your readers.
Second, check to see if your department has a glossary from which you can cut
and paste appropriate entries.
Third, check other Apple manuals on related topics for highly specific definitions
that may not appear elsewhere.
Finally, look in other dictionaries or write your own definition.
You don’t necessarily have to use an existing definition verbatim. Make up your
own variant or examples if appropriate. If an entry contains both a simple
definition and a complex one, and you don’t need both, pick out the part that is
applicable. Feel free to correct errors or misconceptions if you find them.
Appendix E: How to Write a Glossary
165
Download PDF