Switch content of the page by the Role togglethe content would be changed according to the role
IBM Style Guide, The: Conventions for Writers and Editors, 1st edition
Published by IBM Press (October 14, 2011) © 2011
- Francis DeRespinis
- Peter Hayward
- Jana Jenkins
- Amy Laird
- Leslie McDonald
- Eric Radzinski IBM Santa Theresa Labs., San Jose, California
$35.99
- A print text (hardcover or paperback)Â
- Free shipping
- Also available for purchase as an ebook from all major ebook resellers, including InformIT.com
The IBM Style Guide distills IBM wisdom for developing superior content: information that is consistent, clear, concise, and easy to translate. The IBM Style Guide can help any organization improve and standardize content across authors, delivery mechanisms, and geographic locations.
This expert guide contains practical guidance on topic-based writing, writing content for different media types, and writing for global audiences.
Throughout, the authors illustrate the guidance with many examples of correct and incorrect usage.
Writers and editors will find authoritative guidance on issues ranging from structuring information to writing usable procedures to presenting web addresses to handling cultural sensitivities.
The guidelines cover these topics:
This expert guide contains practical guidance on topic-based writing, writing content for different media types, and writing for global audiences.
Throughout, the authors illustrate the guidance with many examples of correct and incorrect usage.
Writers and editors will find authoritative guidance on issues ranging from structuring information to writing usable procedures to presenting web addresses to handling cultural sensitivities.
The guidelines cover these topics:
- Using language and grammar to write clearly and consistently
- Applying punctuation marks and special characters correctly
- Formatting, organizing, and structuring information so that it is easy to find and use
- Using footnotes, cross-references, and links to point readers to valuable, related information
- Presenting numerical information clearly
- Documenting computer interfaces to make it easy for users to achieve their goals
- Writing for diverse audiences, including guidelines for improving accessibility
- Preparing clear and effective glossaries and indexes
Foreword    xviii
About this publication    xxi
Acknowledgments    xxii
About the authors    xxiv
Chapter 1 Language and grammar    1
Abbreviations    1
 General guidelines    1
 Spelled-out forms of abbreviations    3
 Periods with abbreviations    5
 Latin abbreviations    6
 Abbreviations in headings and titles    7
 Abbreviations in glossaries    7
 Abbreviations in indexes    7
 Abbreviations for units of time    8
Anthropomorphism    8
Articles    10
Capitalization    11
 Capitalization styles    11
 Capitalization and abbreviations    13
 Capitalization and colons    14
 Capitalization and figures    14
 Capitalization in general text    14
 Capitalization in glossaries    16
 Capitalization in headings and titles    16
 Capitalization and hyphens    17
 Capitalization in indexes    18
 Capitalization in interfaces    18
 Capitalization of letters as letters    19
 Capitalization in lists    20
 Capitalization for tables in text    20
 Capitalization of computer-related terms    20
Contractions    24
Prepositions    25
Pronouns    27
 Ambiguous pronoun references    27
  ender-neutral pronouns    27
 Personal pronouns    29
 Relative pronouns    29
Spelling    30
Verbs    31
 General guidelines    31
 Mood    32
 Person    33
 Tense    35
 Voice    35
Chapter 2 Punctuation    37
Punctuation marks and special characters    37
 Individual punctuation marks or special characters    37
 Series of punctuation marks or special characters    39
 Common punctuation marks and special characters    39
Apostrophes    41
 Apostrophes in plurals    41
 Apostrophes in possessives    41
Colons    42
 Colons in running text    42
 Colons in headings and titles    43
 Colons after introductory text    43
 Colons and capitalization    44
 Colons with numbers    45
Commas    45
 Commas between clauses    45
 Commas after introductory words and phrases    46
 Commas between items in a series    47
 Commas with nonrestrictive clauses    47
 Commas as separators in numbers    47
 Commas with quotation marks    48
Dashes    48
 En dashes    48
 Em dashes    48
Ellipses    49
 Ellipses in running text    49
 Ellipses in examples and quotations    49
 Ellipses in user interfaces     50
 Spacing and punctuation with ellipses    50
Exclamation points    51
Hyphens    51
 Hyphens with prefixes and suffixes    51
 Hyphens with compound words    53
 Hyphens and capitalization    55
 Hyphens with numbers    56
 Hyphens with ranges    56
Parentheses    57
 Parentheses with abbreviations, symbols, and measurements    57
 Parentheses to form plurals    57
 Parentheses in running text    57
Periods    59
 Periods in running text    59
 Periods with abbreviations    59
 Periods with file name extensions    60
 Periods in headings and titles    61
 Periods after introductory text    61
 Periods with lists    62
 Periods with numbers    63
 Periods with parentheses     63
 Periods with quotation marks     63
Quotation marks    64
 Terminology for quotation marks    64
 Quotation marks for emphasis    64
 Double quotation marks    65
 Single quotation marks    66
 Quotation marks with other punctuation    66
 Typographical considerations for quotation marks    67
Semicolons    67
 Semicolons between independent clauses    68
 Semicolons between items in a series    68
Slashes    68
 Slashes in running text    69
 Slashes in dates    70
 Slashes in fractions    70
 Slashes in mathematical equations    70
 Slashes in path names    70
 Slashes in web addresses    71
Chapter 3 Formatting and organization    73
Headings    73
 Format of headings    73
 Wording of headings    74
 Punctuation with headings     74
 Abbreviations in headings    75
 Lists    75
 Unordered lists    76
 Ordered lists    76
 Definition lists    76
 Capitalization in lists    78
 Wording of list items    78
 Length of lists    79
 Alphabetization and sorting methods of lists    79
 Punctuation in lists    80
 Lead-in wording    81
 Nested lists    83
Procedures    84
 Introducing the procedure    84
 Writing steps    86
 Indicating optional and conditional steps    88
 Handling nonsequential actions    88
 Ending the procedure     89
Figures    90
 Figure captions and legends    91
 Figure numbering    92
 Figure references    92
 Figure placement    93
 Callouts in illustrations    93
 Screen captures    94
Tables    96
 Text in tables    96
 Formatting tables    97
 Table headings    97
 Highlighting    102
 Notes and notices    110
 Revision indicators    114
Chapter 4 Structure    115
Topic-based information    115
 Task topics    116
 Concept topics    120
 Reference topics    124
 Links in topic-based information    128
Books    131
 Sequence of book elements    131
 Book elements and other items that might be included in a book    132
 Books: Front matter    134
 Books: Back matter    139
White papers    141
 Structuring your paper    141
 Writing your paper    142
 Getting your paper reviewed and edited    142
Chapter 5 References    143
Footnotes    143
 Footnotes in printed information    143
 Footnotes in online information    144
 Footnotes in tables    144
References to printed information    144
 General guidelines    144
 References within the same document    145
 References outside the document    146
References to online information    148
 General guidelines    148
 References to IBM information centers    149
 References to web addresses, protocols, and IP addresses    149
 References to webcasts, web conferences, and other online broadcasts    153
 Linking strategies    153
Chapter 6 Numbers and measurements    155
Expressing numbers    155
 Numerals versus words    156
 Separators in numbers     159
 Ranges of numbers    159
 Alignment of numbers in columns    161
 Fractions, percentages, and ratios     162
 Rounding numbers    163
 Different number bases    164
 Number complements    165
Mathematical equations and operational symbols    165
 Multiplication    166
 Exponents    166
Units of measurement    167
 Abbreviations    168
 Multiple dimensions    169
 Tolerances    169
 Dimension lines    169
 Temperatures    169Â
 Multiplier prefixes for units of measurement    170
 Multiplier prefixes for bits and bytes     172
International currency designations    176
 Local currency symbols    177
Dates    178
 Abbreviated forms    179
 Leading zeros    180
 Date ranges    180
Times of the day    181
 Using the 12-hour system    181
 Using the 24-hour system    182
Telephone numbers    182
 National telephone numbers    183
 International telephone numbers    183
 Fictitious telephone numbers    184
Chapter 7 Computer interfaces    185
Commands    185
 Capitalization    185
 Commands, parameters, and options in running text    185
 Commands, parameters, and options in instructions    186
Command syntax     187
 Using text to specify command syntax    188
 Using diagrams to specify command syntax    192
Programming elements    196
 Keywords    196
 Variables    198
Code and command examples    198
Data entry on the command line     201
File names, file types, and directory names    203
Graphical user interface elements    206
 Location of interface elements    206
 Interface element labels    206
 Usage and highlighting for user interface elements    208
Menu instructions and navigation    216
 Menu instructions    216
 Navigation trees    217
 Directories    217
Mouse buttons    218
Keyboard keys    218
 Verbs to use with keyboard keys    218
 Key names    219
 Key combinations    220
Messages    221
 Message types    221
 Components of error, warning, and information messages    222
 Confirmation prompts    230
 References to messages in documentation    231
Chapter 8 Writing for diverse audiences    233
Accessibility    233
International audiences    235
 Style    236
 Grammar    237
 Terminology    240
 Punctuation    241
 Graphics and images    242
Chapter 9 Glossaries    245
Structure of glossary entries    245
Glossary terms    246
Glossary definitions    247
Relationships between terms in a glossary    251
Relationships between the glossary and other information    254
Sort order in a glossary    254
Chapter 10 Indexes     255
Levels of index entries    255
Integration and reuse    255
Size and sorting    256
Index content    256
Index structure    259
 Levels    259
 Locators    261
 Number of subentries    262
 Cross-posting    263
 See and See also references    264
 Other considerations    265
Index entries    266
 Prohibited words    269
Index sorting    270
Appendixes    273
Appendix A. Exceptions for marketing content    274
Appendix B. DITA tags for highlighting    276
Appendix C. Word usage    300
Index    381
About this publication    xxi
Acknowledgments    xxii
About the authors    xxiv
Chapter 1 Language and grammar    1
Abbreviations    1
 General guidelines    1
 Spelled-out forms of abbreviations    3
 Periods with abbreviations    5
 Latin abbreviations    6
 Abbreviations in headings and titles    7
 Abbreviations in glossaries    7
 Abbreviations in indexes    7
 Abbreviations for units of time    8
Anthropomorphism    8
Articles    10
Capitalization    11
 Capitalization styles    11
 Capitalization and abbreviations    13
 Capitalization and colons    14
 Capitalization and figures    14
 Capitalization in general text    14
 Capitalization in glossaries    16
 Capitalization in headings and titles    16
 Capitalization and hyphens    17
 Capitalization in indexes    18
 Capitalization in interfaces    18
 Capitalization of letters as letters    19
 Capitalization in lists    20
 Capitalization for tables in text    20
 Capitalization of computer-related terms    20
Contractions    24
Prepositions    25
Pronouns    27
 Ambiguous pronoun references    27
  ender-neutral pronouns    27
 Personal pronouns    29
 Relative pronouns    29
Spelling    30
Verbs    31
 General guidelines    31
 Mood    32
 Person    33
 Tense    35
 Voice    35
Chapter 2 Punctuation    37
Punctuation marks and special characters    37
 Individual punctuation marks or special characters    37
 Series of punctuation marks or special characters    39
 Common punctuation marks and special characters    39
Apostrophes    41
 Apostrophes in plurals    41
 Apostrophes in possessives    41
Colons    42
 Colons in running text    42
 Colons in headings and titles    43
 Colons after introductory text    43
 Colons and capitalization    44
 Colons with numbers    45
Commas    45
 Commas between clauses    45
 Commas after introductory words and phrases    46
 Commas between items in a series    47
 Commas with nonrestrictive clauses    47
 Commas as separators in numbers    47
 Commas with quotation marks    48
Dashes    48
 En dashes    48
 Em dashes    48
Ellipses    49
 Ellipses in running text    49
 Ellipses in examples and quotations    49
 Ellipses in user interfaces     50
 Spacing and punctuation with ellipses    50
Exclamation points    51
Hyphens    51
 Hyphens with prefixes and suffixes    51
 Hyphens with compound words    53
 Hyphens and capitalization    55
 Hyphens with numbers    56
 Hyphens with ranges    56
Parentheses    57
 Parentheses with abbreviations, symbols, and measurements    57
 Parentheses to form plurals    57
 Parentheses in running text    57
Periods    59
 Periods in running text    59
 Periods with abbreviations    59
 Periods with file name extensions    60
 Periods in headings and titles    61
 Periods after introductory text    61
 Periods with lists    62
 Periods with numbers    63
 Periods with parentheses     63
 Periods with quotation marks     63
Quotation marks    64
 Terminology for quotation marks    64
 Quotation marks for emphasis    64
 Double quotation marks    65
 Single quotation marks    66
 Quotation marks with other punctuation    66
 Typographical considerations for quotation marks    67
Semicolons    67
 Semicolons between independent clauses    68
 Semicolons between items in a series    68
Slashes    68
 Slashes in running text    69
 Slashes in dates    70
 Slashes in fractions    70
 Slashes in mathematical equations    70
 Slashes in path names    70
 Slashes in web addresses    71
Chapter 3 Formatting and organization    73
Headings    73
 Format of headings    73
 Wording of headings    74
 Punctuation with headings     74
 Abbreviations in headings    75
 Lists    75
 Unordered lists    76
 Ordered lists    76
 Definition lists    76
 Capitalization in lists    78
 Wording of list items    78
 Length of lists    79
 Alphabetization and sorting methods of lists    79
 Punctuation in lists    80
 Lead-in wording    81
 Nested lists    83
Procedures    84
 Introducing the procedure    84
 Writing steps    86
 Indicating optional and conditional steps    88
 Handling nonsequential actions    88
 Ending the procedure     89
Figures    90
 Figure captions and legends    91
 Figure numbering    92
 Figure references    92
 Figure placement    93
 Callouts in illustrations    93
 Screen captures    94
Tables    96
 Text in tables    96
 Formatting tables    97
 Table headings    97
 Highlighting    102
 Notes and notices    110
 Revision indicators    114
Chapter 4 Structure    115
Topic-based information    115
 Task topics    116
 Concept topics    120
 Reference topics    124
 Links in topic-based information    128
Books    131
 Sequence of book elements    131
 Book elements and other items that might be included in a book    132
 Books: Front matter    134
 Books: Back matter    139
White papers    141
 Structuring your paper    141
 Writing your paper    142
 Getting your paper reviewed and edited    142
Chapter 5 References    143
Footnotes    143
 Footnotes in printed information    143
 Footnotes in online information    144
 Footnotes in tables    144
References to printed information    144
 General guidelines    144
 References within the same document    145
 References outside the document    146
References to online information    148
 General guidelines    148
 References to IBM information centers    149
 References to web addresses, protocols, and IP addresses    149
 References to webcasts, web conferences, and other online broadcasts    153
 Linking strategies    153
Chapter 6 Numbers and measurements    155
Expressing numbers    155
 Numerals versus words    156
 Separators in numbers     159
 Ranges of numbers    159
 Alignment of numbers in columns    161
 Fractions, percentages, and ratios     162
 Rounding numbers    163
 Different number bases    164
 Number complements    165
Mathematical equations and operational symbols    165
 Multiplication    166
 Exponents    166
Units of measurement    167
 Abbreviations    168
 Multiple dimensions    169
 Tolerances    169
 Dimension lines    169
 Temperatures    169Â
 Multiplier prefixes for units of measurement    170
 Multiplier prefixes for bits and bytes     172
International currency designations    176
 Local currency symbols    177
Dates    178
 Abbreviated forms    179
 Leading zeros    180
 Date ranges    180
Times of the day    181
 Using the 12-hour system    181
 Using the 24-hour system    182
Telephone numbers    182
 National telephone numbers    183
 International telephone numbers    183
 Fictitious telephone numbers    184
Chapter 7 Computer interfaces    185
Commands    185
 Capitalization    185
 Commands, parameters, and options in running text    185
 Commands, parameters, and options in instructions    186
Command syntax     187
 Using text to specify command syntax    188
 Using diagrams to specify command syntax    192
Programming elements    196
 Keywords    196
 Variables    198
Code and command examples    198
Data entry on the command line     201
File names, file types, and directory names    203
Graphical user interface elements    206
 Location of interface elements    206
 Interface element labels    206
 Usage and highlighting for user interface elements    208
Menu instructions and navigation    216
 Menu instructions    216
 Navigation trees    217
 Directories    217
Mouse buttons    218
Keyboard keys    218
 Verbs to use with keyboard keys    218
 Key names    219
 Key combinations    220
Messages    221
 Message types    221
 Components of error, warning, and information messages    222
 Confirmation prompts    230
 References to messages in documentation    231
Chapter 8 Writing for diverse audiences    233
Accessibility    233
International audiences    235
 Style    236
 Grammar    237
 Terminology    240
 Punctuation    241
 Graphics and images    242
Chapter 9 Glossaries    245
Structure of glossary entries    245
Glossary terms    246
Glossary definitions    247
Relationships between terms in a glossary    251
Relationships between the glossary and other information    254
Sort order in a glossary    254
Chapter 10 Indexes     255
Levels of index entries    255
Integration and reuse    255
Size and sorting    256
Index content    256
Index structure    259
 Levels    259
 Locators    261
 Number of subentries    262
 Cross-posting    263
 See and See also references    264
 Other considerations    265
Index entries    266
 Prohibited words    269
Index sorting    270
Appendixes    273
Appendix A. Exceptions for marketing content    274
Appendix B. DITA tags for highlighting    276
Appendix C. Word usage    300
Index    381
Francis DeRespinis, Peter Hayward, Jana Jenkins, Amy Laird, Leslie McDonald, and Eric Radzinski are members of the IBM Style and Word Usage Council, a workgroup of senior editors who represent key product brands in IBM.
Need help? Get in touch
Play
Privacy and cookies
By watching, you agree Pearson can share your viewership data for marketing and analytics for one year, revocable by deleting your cookies.
Pearson eTextbook: What’s on the inside just might surprise you
They say you can’t judge a book by its cover. It’s the same with your students. Meet each one right where they are with an engaging, interactive, personalized learning experience that goes beyond the textbook to fit any schedule, any budget, and any lifestyle.Â
Digital Learning NOW
Extend your professional development and meet your students where they are with free weekly Digital Learning NOW webinars. Attend live, watch on-demand, or listen at your leisure to expand your teaching strategies. Earn digital professional development badges for attending a live session.