IBM Style Guide, The
Conventions for Writers and Editors
Will be published approx. on 2. November 2011
Book
Paperback/Softback
416 pages
978-0-13-210130-1 (ISBN)
Description
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:
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
The IBM Style Guide can help any organization or individual create and manage content more effectively. The guidelines are especially valuable for businesses that have not previously adopted a corporate style guide, for anyone who writes or edits for IBM as an employee or outside contractor, and for anyone who uses modern approaches to information architecture.
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
The IBM Style Guide can help any organization or individual create and manage content more effectively. The guidelines are especially valuable for businesses that have not previously adopted a corporate style guide, for anyone who writes or edits for IBM as an employee or outside contractor, and for anyone who uses modern approaches to information architecture.
More details
Series
Language
English
Place of publication
Armonk
United States
Publishing group
Pearson Education (US)
Target group
Professional and scholarly
Adult education
Product notice
Paperback (trade)
Unsewn / adhesive bound
Dimensions
Height: 232 mm
Width: 177 mm
Thickness: 27 mm
Weight
653 gr
ISBN-13
978-0-13-210130-1 (9780132101301)
Schweitzer Classification
Other editions
Additional editions
Francis DeRespinis | Peter Hayward | Jana Jenkins
IBM Style Guide, The
Conventions for Writers and Editors
E-Book
10/2011
1st Edition
IBM Press
€41.99
Available for download
Francis DeRespinis | Peter Hayward | Jana Jenkins
IBM Style Guide, The
Conventions for Writers and Editors
E-Book
10/2011
1st Edition
IBM Press
from
€33.49
Available for download
Persons
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.
Content
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