IBM Style Guide, The: Conventions for Writers and Editors

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