The IBM Style Guide: Conventions for Writers and Editors

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 indexesThe 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.

CONTENTS:

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