IBM Style Guide, The: Conventions for Writers and Editors(IBM Press)

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.

Table of 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

About the Author :
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.