12-hour system (time of day), 181-182
24-hour system (time of day), 182
+ (plus sign) GUI element, 215
- (minus sign) GUI element, 215
a, an, 10-11
abbreviations, 1-7
dates, 179-180
Latin abbreviations, 6
number abbreviations, defining, 175-176
parentheses with, 57
periods in, 5-6, 59 See references in glossaries, 252
spelled-out forms, 3-4
in titles, 7
units of measurement, 168
units of time, 8
abstract in white papers, 141
accessibility, 233-235
indexes, 258
syntax diagrams, 192
tables, 97
active voice, 35-36
adjectives, numbers in compound, 161
alignment of numbers in columns, 161-162
alphabetization. See sort order
alternative text for images, 234
American system (units of measurement), 167
API reference topics in indexes, 257
apostrophes, 41-42
appendixes in books, 139-140
approval process for white papers, 142
Attention notices, 112
back matter in books, 139-140
backslashes. See slashes
bases of numbers, 164-165
bibliographies in books, 140
bidirectional languages, 242
billion, 158
binary numbers, 164-165
bits
capitalization of, 21
multiplier prefixes, 172-175
body text. See running text
books. See also printed information
back matter, 139-140
element sequence, 131-132
elements in, 132-134
front matter, 134-138
revision indicators, 114
bytes
capitalization of, 21
multiplier prefixes, 172-175
callouts in illustrations, 93-94
capitalization, 11-24
commands, 185
computer-related terms, 20-24
directory names, 203
figure captions and legends, 91
figures, 14
file names, 203
file types, 203
general text, 14-16
glossaries, 16
graphical user interface element labels, 206
headings and titles, 16
headline-style, 11-12
interfaces, 18
letters as letters, 19
sentence-style, 11
table captions and legends, 98
tables, 20
figures, 91-92
tables, 98-99
CAUTION notices, 112-113
channel commands, capitalization of, 22
chapter titles in books, 132
check boxes GUI element, 208
clauses
independent
commas between, 45
semicolons between, 68
nonrestrictive clauses, commas in, 47
that in, 275
code examples, 198-200
colons, 42-45
in headings and titles, 43
after introductory text, 43-44
with numbers, 45
in running text, 42-43
colors, international audence usage, 242
columns, number alignment, 161-162
combinations of keyboard keys, 220-221
command examples, 198-200
command line, data entry on, 201-203
commands
capitalization, 185
command syntax, 187
in running text, 188-191
in syntax diagrams, 192-196
in instructions, 186-187
in running text, 185-186
commas, 45-48
between independent clauses, 45
after introductory words and phrases, 46
marketing content exceptions, 274
with nonrestrictive clauses, 47
quotation marks and, 48, 66-67
serial commas, 241
between series items, 47
comment forms in books, 140
comments section in books, 138
complements of numbers, 165
component names in indexes, 259
compound adjectives, numbers in, 161
compound words, hyphens with, 53-54
computer-related terms, capitalization of, 20-24
concept topics, 120-124
example of, 123-124
headings, 121-122
in indexes, 256
length of, 122
structure of, 122
conditional procedure steps, 88
conditions, capitalization of, 21
confirmation prompts
defined, 221-222
when to use, 230
conjunctive adverbs, 68
container topics in indexes, 257
content in indexes, 256-258
control words, capitalization of, 21
conventions section in books, 137-138
coordinate clauses, 32
coordinating conjunctions, 45, 68
copyright statement in books, 135
cross-posting index entries, 263-264
cross-references
in glossaries, 251-253
to online information, 148-153
to printed information, 144-148
curly quotation marks, 67
currency designations, 176-178
DANGER notices, 113
dangling modifiers, 32
dashes, 48-49
em dashes, 48-49
en dashes, 48
marketing content exceptions, 274
data areas, capitalization of, 21
data entry on command line, 201-203
data sets, capitalization of, 21
dates, 178-181
abbreviations, 179-180
leading zeros in, 180
marketing content exceptions, 274
ranges, 180-181
slashes in, 70
deep links, 153
defining number abbreviations, 175-176
definite articles, 10-11
definition lists, 76-78
definitions (glossary), 247-251
dependent clauses, commas and, 46
device orders, capitalization of, 22
dimension lines, 169
directories
navigating, 217
DITA tags for highlighting, 276-299
books
back matter, 139-140
element sequence, 131-132
elements in, 132-134
front matter, 134-138
topics
concept topics, 120-124
defined, 115
links in, 128-131
reference topics, 124-128
task topics, 116-120
types of, 115
white papers, 141-142
documentation
accessibility guidelines, 233-235
references to messages in, 231
double quotation marks, 65
drop-down lists (GUI element), 209
dual list boxes (GUI element), 209
dump names, capitalization of, 21
editing white papers, 142
edition notice in books, 135
element sequence
in back matter, 139
in books, 131-132
in front matter, 134
in white papers, 141
ellipses, 49-50
in examples and quotations, 49
marketing content exceptions, 275
in running text, 49
spacing and punctuation marks with, 50
in user interfaces, 50
emphasis, quotation marks for, 64
en dashes, 48
end matter in white papers, 141
ending procedures, 89-90
ending tasks, 118
English-as-second-language speakers. See international audiences
entries (indexes)
content types, 256-258
integration and reuse, 255-256
structure, 259-266
cross-posting, 263-264
locators, 261-262
number of subentries, 262-263 See and See also references, 264-265
writing, 266-269
error messages
components of, 222-230
defined, 221
estimating index size, 256
examples
code examples, 198-200
command examples, 198-200
in indexes, 258
web addresses, IP addresses in, 151-152
exclamation points, 51
exponents, 166
extensions. See file name extensions
feedback section in books, 138
feet, abbreviations, 168
fictitious telephone numbers, 184
fields GUI element, 209
figure list in books, 136
figures, 90-95. See also images
callouts, 93-94
capitalization and, 14
captions and legends, 91-92
numbering, 92
placement, 93
references, 92-93
screen captures, 94-95
file name extensions, 203-205
file types, 203-205
files in indexes, 258
first person pronouns, 33-34
flipped images, 242
fonts
for figure captions, 91-92
for table captions, 98
footers, running footers in books, 133
footnotes, 143-144
in online information, 144
in printed information, 143
in tables, 144
form numbers in books, 132
formatting. See also organization; structure
Attention notices, 112
CAUTION notices, 112-113
code and command examples, 198-200
command syntax, 187
in running text, 188-191
in syntax diagrams, 192-196
DANGER notices, 113
data entry on command line, 201-203
directory names, 203-205
figure captions, 91-92
file names, 203-205
file types, 203-205
headings, 73
highlighting conventions, 102-110
instructions. See instructions
message variables, 229
table captions, 98
tables, 97
web addresses, 152
forward slashes. See slashes
front matter in books, 134-138
fully qualified host names, 151
functions, capitalization of, 23
future tense, 35
gender-neutral pronouns, 27-28
geographical maps, usage guidelines, 242
gerunds as index entries, 266-267
glossaries
abbreviations in, 7
in books, 140
capitalization in, 16
definitions in, 247-251
indexing, 259
relationships with other information, 254
relationships between terms, 251-253 See references, 251-253 See also references, 251-253
sort order, 254
structure of entries, 245-246
terms in, 246-247
grammar rules. See also organization
abbreviations. See abbreviations
capitalization. See capitalization
headings. See headings
index entries, 266-269
for international audiences, 237-240
lists. See lists
numbers. See numbers
prepositions, 25-26
indexes, 268
web address references, 150-151
pronouns, 27-29
ambiguous references, 27
gender neutrality, 27-28
relative pronouns, 29
punctuation. See punctuation
spelling, 30
tables. See tables
verbs. See verbs
graphical user interface (GUI) elements
capitalization in, 18-19
check boxes, 208
combination boxes, 208
definitions, 208-215
drop-down lists, 209
dual list boxes, 209
fields, 209
group boxes, 209
highlighting, 208-215
icons, 210
labels, 206-215
list boxes, 210
location, 206
- (minus sign), 215
notebooks, 211
pages, 211
panes, 211
+ (plus sign), 215
portals, 212
portlets, 212
prepositions with, 208-215
push buttons, 212
radio buttons, 212
sliders, 213
spin buttons, 213
system tray, 213
tabs, 213
tables, 96-102
taskbars, 214
toolbars, 214
twisties, 214
verbs with, 208-215
windows, 215
wizards, 215
graphics. See images
group boxes GUI element, 209
hardware components, capitalization of, 22
headers, running headers in books, 133
headings, 73-75
capitalization in, 16
colons in, 43
for concept topics, 121-122
formatting, 73
marketing content exceptions, 275
periods in, 61
punctuation, 74-75
for reference topics, 124-125
for tables, 97-98
for task topics, 116-117
writing, 74
headline-style capitalization, 11-12. See also capitalization
hexadecimal numbers, 164-165
highlighting. See also formatting
conventions, 102-110
DITA tags for, 276-299
host names, 151
hyphens, 51-56
compound words, 53-54
en dashes versus, 48
letter-by-letter sort order, 80
numbers, 56
prefixes and suffixes, 51-53
IBM information centers, cross-references to, 149
icons GUI element, 210
IEC (International Electrotechnical Commission), 174
illustrations. See figures
images. See also figures
alternative text for, 234
flipping, 242
in indexes, 258
international audience usage, 242
imperative mood, 32
inches, abbreviations, 168
indefinite articles, 10-11, 60
independent clauses
commas between, 45
semicolons between, 68
indexes
abbreviations in, 7
in books, 140
capitalization in, 18
content types, 256-258
defined, 255
integration and reuse, 255-256
levels of entries, 255, 259-260
size estimates, 256
sort order, 270-271
structure, 259-266
cross-posting, 263-264
locators, 261-262
number of subentries, 262-263 See and See also references, 264-265
writing entries, 266-269
indicative mood, 33
indicators, capitalization of, 21
information messages
components of, 222-230
defined, 221
inline links, 130-131
instructions that contain commands, 186-187
integration of indexes, 255-256
intended audience in books, 137
interdocument cross-references, 146-148
international audiences, 235-242
grammar rules, 237-240
image guidelines, 242
punctuation guidelines, 241
style guidelines, 236-237
terminology guidelines, 240-241
international currency designations, 176-178
International Electrotechnical Commission (IEC), 174
International Standard Book Number (ISBN) in cross-references, 148
International System of Units (SI), 167
international telephone numbers, 183-184
intradocument cross-references, 145-146
introducing procedures, 84-86. See also lead-in wording
introduction
for task topics, 117-118
in white papers, 141
introductory text
commas after, 46
periods after, 61-62
IP addresses
cross-references to, 149-152
defined, 149
marketing content exceptions, 275
IP loopback address, 152
ISBN (International Standard Book Number) in cross-references, 148
keyboard keys
combinations of, 220-221
names of, 219-220
verbs for, 218
language rules. See grammar rules
Latin abbreviations, 6
lead-in wording for lists, 81-83. See also introducing
leading zeros in dates, 180
legal notices
in books, 140
in indexes, 258
in white papers, 141
legends
figures, 91-92
tables, 98-99
length of lists, 79
letter-by-letter sort order, 80, 254
letters as letters, capitalization of, 19
libraries, capitalization of, 21
links, 153-154
in topic-based information, 128-131
list boxes GUI element, 210
lists, 75-84
definition lists, 76-78
of figures in books, 136
grammar rules, 78-79
lead-in wording, 81-83
length of, 79
nested lists, 83-84
ordered lists, 76
periods with, 62
punctuation, 80-81
sort order, 79-80
of tables in books, 136-137
unordered lists, 76
local currency designations, 177-178
locators in index entries, 261-262
logs, capitalization of, 22
loopback address, 152
machine instructions, capitalization of, 22
macros, capitalization of, 22
main entries (indexes), 255
maps, usage guidelines, 242
marketing content, exceptions for, 274-275
master indexes, 255-256
mathematical equations, 70, 165
measurements, parentheses with, 57. See also numbers; units of measurement
menus GUI element, 210, 216-217
messages
components of, 222-230
confirmation prompts, 230
explanations, 223-225
identifiers, 222
in documentation, 231
return codes, 229-230
text, 223
types of, 221-222
user responses, 225-227
variables, 227-229
million, 158
minus sign (-) GUI element, 215
money, currency designations, 176-178
mood, 32
mouse buttons, 218
multiple dimensions, 169
multiplication, 166
multiplier prefixes
bits, bytes, 172-175
units of measurement, 170-172
names
keyboard keys, 219-220
punctuation marks, special characters, 39
national flags, usage guidelines, 242
National Institute of Standards and Technology (NIST) website, 167
national telephone numbers, 183
navigation trees, 217
negative currency values, 178
nested lists, 83-84
NIST (National Institute of Standards and Technology) website, 167
non-English speakers. See international audiences
nonrestrictive clauses, 30, 47
nonsequential procedure steps, 88-89
notebooks (GUI element), 211
notes, 110-112
notices
Attention, 112
CAUTION, 112-113
DANGER, 113
nouns
abbreviations as, 2
as index entries, 266-267
numbering
figures, 92
tables, 100-101
numbers, 155-156
abbreviations, defining, 175-176
alignment in columns, 161-162
bases, 164-165
bits/bytes, multiplier prefixes, 172-175
colons with, 45
commas in, 47
complements, 165
currency designations, 176-178
dates, 178-181
decimal separator, 155
form numbers in books, 132
fractions, 162
hyphens with, 56
mathematical equations, 165
million, billion, and trillion, 158
numerals versus spelled-out, 156-158
operational symbols, 165
page numbering in books, 132
percentages, 162
periods with, 63
plural form, 156
ranges, 159-161
ratios, 163
rounding, 163
separators, 159
telephone numbers, 182-184
times, 181-182
units of measurement, 167-172
version and release numbers in book titles, 134
numerals, numbers as, 156-158
octal numbers, 164-165
online broadcasts, cross-references to, 153
online information
cross-references to, 148-153
footnotes in, 144
revision indicators, 114
operational symbols, 165
optional procedure steps, 88
options of commands
capitalization, 185
command syntax, 187
in running text, 188-191
in syntax diagrams, 192-196
in instructions, 186-187
in running text, 185-186
ordered lists, 76
organization. See also formatting; structure
figures, 90-95
callouts, 93-94
captions and legends, 91-92
numbering, 92
placement, 93
references, 92-93
screen captures, 94-95
headings, 73-75
abbreviations in, 75
formatting, 73
punctuation, 74-75
writing, 74
highlighting conventions, 102-110
lists, 75-84
capitalization in, 78
definition lists, 76-78
grammar rules, 78-79
lead-in wording, 81-83
length of, 79
nested lists, 83-84
ordered lists, 76
punctuation, 80-81
sort order, 79-80
unordered lists, 76
notes and notices, 110-113
procedures, 84-90
conditional steps, 88
ending, 89-90
introducing, 84-86
nonsequential steps, 88-89
optional steps, 88
writing steps, 86-88
revision indicators, 114
tables, 96-102
captions and legends, 98-99
formatting, 97
grammar rules in, 96-97
headings, 97-98
numbering, 100-101
placement, 102
references, 101
overviews in indexes, 259
page numbering in books, 132. See also locators
pages GUI element, 211
panes GUI element, 211
parameters of commands
capitalization, 185
command syntax, 187
in running text, 188-191
in syntax diagrams, 192-196
in instructions, 186-187
in running text, 185-186
parentheses, 57-58
abbreviations, symbols, measurements, 57
currency designations, 178
periods with, 63
plurals, 57
running text, 57-58
part titles in books, 132
parts in books, 132
passive voice, 35-36
past tense, 35
path names, slashes in, 70, 203
periods, 59-63
file name extensions, 60
headings and titles, 61
after introductory text, 61-62
lists, 62
numbers, 63
parentheses, 63
running text, 59
person for verbs, 33-34
personal pronouns, 29
first person, 33-34
second person, 34
third person, 34
phone numbers. See telephone numbers
placement
figures, 93
tables, 102
plural abbreviations, 2
plural form of numbers, 156
plurals, 241
apostrophes in, 41
parentheses for, 57
plus sign (+) GUI element, 215
portals GUI element, 212
portlets GUI element, 212
possessive form
apostrophes, 41-42
abbreviations and, 3
prepositions and, 26
precision, rounding numbers, 163
preface in books, 137
prefixes
hyphens with, 51-53
multiplier prefixes
bits, bytes, 172-175
units of measurement, 170-172
prepositions, 25-26
indexes, 268
web address references, 150-151
prerequisites
in books, 137
for task topics, 118
present tense, 35
cross-references to, 144-148
footnotes in, 143
procedures, 84-90
conditional steps, 88
ending, 89-90
introducing, 84-86
nonsequential steps, 88-89
optional steps, 88
writing steps, 86-88
product names in indexes, 259
product overviews in indexes, 259
program execution stages, capitalization of, 24
program names, capitalization of, 23
programming concepts, capitalization of, 23
programming elements
code examples, 198-200
keywords, 196-197
variables, 198
programming languages, capitalization of, 23
prohibited words in indexes, 269
pronouns, 27-29
ambiguous references, 27
gender neutrality, 27-28
personal pronouns, 29
first person, 33-34
second person, 34
third person, 34
relative pronouns, 29
protocols
cross-references to, 149-152
defined, 149
marketing content exceptions, 275
publication information in white papers, 141
publication titles in books, 134
apostrophes, 41-42
exclamation points, 51
figure captions and legends, 91
graphical user interface element labels, 206-207
headings, 74-75
international audiences, guidelines for, 241
introducing procedures, 84-86
lists, 80-81
menu instructions, 216
message variables, 229
names of, 39
numbers. See numbers
parentheses, 57-58
quotation marks, 64-67
semicolons, 67-68
series of punctuation marks or special characters, 39
single punctuation marks or special characters, 37-38
slashes, 68-71
sorting in indexes, 270
table captions and legends, 98
web addresses, 152
push buttons GUI element, 212
quotation marks, 64-67
commas and, 48
double, 65
for emphasis, 64
with other punctuation, 66-67
periods with, 63
single, 66
terminology, 64
typography, 67
quotations, ellipses in, 49
radio buttons GUI element, 212
railroad diagrams. See syntax diagrams
ranges
dates, 180-181
hyphens with, 56
numbers, 159-161
ratios, 163
reader comment forms in books, 140
reason codes in messages, 229-230
reference topics, 124-128
example of, 126-128
headings, 124-125
in indexes, 257
length of, 126
structure of, 125-126
cross-references
online information, 148-153
printed information, 144-148
figures, 92-93
footnotes, 143-144
links, 153-154
tables, 101
related information in books, 137
related topics, links to, 129
relative pronouns, 29
release numbers in book titles, 134
reserved words. See keywords
return codes in messages, 229-230
reuse of indexes, 255-256
reviewing white papers, 142
revision indicators, 114
rounding numbers, 163
running headers/footers in books, 133
samples in indexes, 258
scenarios in indexes, 258
screen captures, 94-95
second person pronouns, 34
secondary entries (indexes), 255 See references
in glossaries, 251-253
in indexes, 264-265 See also references
in glossaries, 252-253
in indexes, 264-265
semicolons, 67-68
sentence-style capitalization, 11. See also capitalization
separators in numbers, 159
sequence of elements
in backmatter, 139
in books, 131-132
in front matter, 134
in white papers, 141
serial commas, 241
series
of punctuation marks or special characters, 39
semicolons in, 68
SI (International System of Units), 167
single quotation marks, 66
size of indexes, estimating, 256
dates, 70
fractions, 70
mathematical equations, 70
running text, 69-70
sliders GUI element, 213
software components, capitalization of, 24
glossaries, 254
indexes, 270-271
lists, 79-80
spacing with ellipses, 50
abbreviations with, 57
currency symbols, 177
definitions in books, 139
in indexes, 269-270
international audience usage, 242
names of, 39
operational symbols, 165
series of, 39
single usage, 37-38
special codes, capitalization of, 21
spelled-out forms of abbreviations, 3-4
spelled-out numbers, numerals versus, 156-158
spelling, 30
spin buttons GUI element, 213
status, capitalization of, 21
status words, capitalization of, 21
steps in procedures
conditional, 88
nonsequential, 88-89
optional, 88
writing, 86-88
storage areas, capitalization of, 24
straight quotation marks, 67
structure. See also document structure; formatting; organization
indexes, 259-266
cross-posting, 263-264
locators, 261-262
number of subentries, 262-263 See and See also references, 264-265
style guidelines for international audiences, 236-237
subentries (indexes), number of, 262-263
subheadings, links to, 129
subjunctive mood, 33
suffixes, hyphens with, 51-53
summary of changes in books, 138
supertasks, 116
symbolic names, capitalization of, 21
symbols. See special characters
system stages, capitalization of, 24
system tray GUI element, 213
table list in books, 136-137
table of contents
in books, 135
in white papers, 141
tables, 96-102. See also graphical user interface (GUI) elements
capitalization in, 20
captions and legends, 98-99
footnotes in, 144
formatting, 97
grammar rules in, 96-97
headings, 97-98
in indexes, 258
numbering, 100-101
placement, 102
references, 101
tables GUI element, 214
tabs GUI element, 213
example of, 119-120
headings, 116-117
in indexes, 256
length of, 119
steps in, 119
structure of, 117-118
taskbars GUI element, 214
telephone numbers, 182-184
fictitious, 184
international, 183-184
national, 183
temperatures, 169
tense of verbs, 35
terminology
in index entries, 266-269
international audiences, guidelines for, 240-241
word usage, 300-380
terminology section in books, 137
terms (glossary), 246-247, 251-253
tertiary entries (indexes), 255
text, alternative for images, 234. See also running text
the, 10-11
third person pronouns, 34
time, 181-182
12-hour system, 181-182
24-hour system, 182
colons in, 45
time zones, 182
titles
abbreviations in, 7
capitalization in, 16
chapter titles in books, 132
colons in, 43
part titles in books, 132
periods in, 61
publication titles in books, 134
tolerances, 169
toolbars GUI element, 214
tone
contractions, 24
ellipses, 49
exclamation points, 51
first person, 33
topics. See also printed information
concept topics, 120-124
example of, 123-124
headings, 121-122
length of, 122
structure of, 122
defined, 115
in indexes, 256-257
links in, 128-131
inline links, 130-131
to related topics, 129
to subheadings, 129
reference topics, 124-128
example of, 126-128
headings, 124-125
length of, 126
structure of, 125-126
task topics, 116-120
example of, 119-120
headings, 116-117
length of, 119
steps in, 119
structure of, 117-118
types of, 115
transitional phrases, 68
trillion, 158
tutorials in indexes, 258
12-hour system (time of day), 181-182
24-hour system (time of day), 182
twisties (GUI element), 214
type size in printed documents, 134
typography of quotation marks, 67
United States customary system (units of measurement), 167
units of measurement, 167-168. See also numbers
abbreviations, 168
dimension lines, 169
multiple dimensions, 169
multiplier prefixes, 170-175
temperatures, 169
tolerances, 169
units of time, abbreviations for, 8
unordered lists, 76
unqualified host names, 151
URLs. See web addresses
user interface elements. See graphical user interface (GUI) elements
user interface elements in indexes, 259
user interfaces, ellipses in, 50
user responses to messages, 225-227
variables, 198
command syntax, 187
running text, 188-191
syntax diagrams, 192-196
message, 227-229
verbs, 31-36
abbreviations as, 2
anthropomorphism, 8
commands as, 186
index entries, 266-267
international audience usage, 237-238
keyboard keys, 218
keywords as, 197
mood, 32
mouse buttons, 218
person, 33-34
tense, 35
voice, 35-36
web address references, 150-151
version numbers in book titles, 134
voice, passive versus active, 35-36
warning messages
components of, 222-230
defined, 221
warnings, 112
cross-references to, 149, 151-152
defined, 149
marketing content exceptions, 275
web conferences, cross-references to, 153
webcasts, cross-references to, 153
which, 29
white papers, 141-142. See also printed information
approval process, 142
cross-references to, 148
element sequence, 141
guidelines for body text, 142
who, 29
windows GUI element, 215
wizards GUI element, 215
word-by-word sort order, 254, 270-271
word usage, 300-380
words, numbers as, 156-158
writing style. See grammar rules
zeros, leading zeros in dates, 180
18.222.104.196