The New copy of this book will include any supplemental materials advertised. Please check the title of the book to determine if it should include any access cards, study guides, lab manuals, CDs, etc.
The eBook copy of this book is not guaranteed to include any supplemental materials. Typically, only the book itself is included. This is true even if the title states it includes any access cards, study guides, lab manuals, CDs, etc.
The definitive reference for technical writers, editors, and documentation managers,Read Me First! A Style Guide for the Computer Industry, Third Edition,has been revised and updated to cover everything from creating screencasts and referencing web sites to writing for wikis. This award-winning guide to creating clear, consistent, and easy-to-understand documentation covers everything from grammar and writing style to typographic and legal guidelines. The authors, who are senior editors and writers at Sun Microsystems, share their extensive experience and provide practical tips and recommendations, including guidance on hiring writers, working with illustrators, managing schedules and workflow, and more. The third edition features new chapters on Writing for wikis and encouraging wiki collaboration Creating screencasts, using screencast terminology, and guidelines for writing narration Creating alternative text for nontext elements such as screen captures, multimedia content, illustrations, and diagrams It also includes new tables for symbol name conventions, for common anthropomorphisms, and for common idioms and colloquialisms. An updated and expanded recommended reading list suggests additional resources.
The Members of Sun Technical Publications are award-winning senior editors and writers for Sun Microsystems, Inc.
Table of Contents
Chapter 1: Mechanics of Writing 25 Capitalization 25 Contractions 29 Gerunds and Participles 29 Numbers and Numerals 31 Pronouns 34 Technical Abbreviations, Acronyms, and Units of Measurement 35 Punctuation 39
Chapter 2: Constructing Text 57 Headings 58 Lists 62 Tables 70 Code Examples 75 Error Messages 76 Cross-References 77 Endnotes, Footnotes, and Bibliographies 79 Notes, Cautions, and Tips 82 Key Name Conventions 84 Symbol Name Conventions 87
Chapter 3: Writing Style 89 Why Is Style Important? 89 Stylistic Principles 90 Some Basic Elements of Style 90 Construct Scannable Paragraphs, Headings, and Lists 95 Write for the Reader 99 Avoid Style That Could Offend the Reader 102 Common Writing Problems to Avoid 105
Chapter 5: Online Writing Style 121 About These Guidelines 121 Solving Online Writing Problems 122 Creating an Effective Online Document Structure 122 Writing Online Topics 124 Constructing Scannable Text in Online Documents 124 Preserving Context in Online Documents 125
Chapter 6: Constructing Links 127 About These Guidelines 127 Where to Place Links 128 General Linking Strategies 129 Guidelines for Crafting Link Text 135
Chapter 7: Writing Tasks, Procedures, and Steps 139 Understanding the Relationship Among Tasks, Procedures, and Steps 139 Developing Task Information 140 Writing Procedures 149 Writing Steps 153 Checking for Structural Problems 162
Chapter 8: Writing for an International Audience 165 Guidelines for Writing for Translation 166 Cultural and Geographic Sensitivity 166 Definitions and Word Choice 168 Grammar and Word Usage 171 Numbers, Symbols, and Punctuation 175 Illustrations and Screen Captures 176
Chapter 9: Legal Guidelines 183 Understanding Copyrights 184 Protecting Trademarks 188 Referencing External Web Sites 194 Protecting Confidential Information 196
Chapter 10: Types of Technical Documents 203 What Is a Documentation Set? 203 Documentation Plans 204 Abstracts 206 Structure of Manuals 206 Descriptions of the Manual Parts 208 Types of Hardware Manuals 211 Types of Software Manuals 212 Release Notes and Product Notes 213 Other Product Documents 214 Training Documentation 215
Chapter 11: Working With an Editor 217 Technical Editor's Role 217 Editor's Role in Producing Online Documents 218 Types of Editing 218 Planning Ahead for Editing 224 Submitting a Document for Editing 224 Editing Marks 225 Creating a Style Sheet 225
Chapter 12: Working With Illustrations 229 Working With an Illustrator 230 Understanding Illustration Files 231 Types of Illustrations 232 Placing Illustrations 235 Writing Captions for Illustrations 237 Writing Callouts for Illustrations 238 Creating Quality Screen Captures 243 Creating Leader Lines 244 Simplifying Online Illustrations 244
Chapter 13: Writing Alternative Text for Nontext Elements 245 Section 508 Requirements Overview 245 General Guidelines for Writing Alternative Text 246 Writing About Nontext Elements 248
Chapter 14: Documenting Graphical User Interfaces 265 Using GUI Terminology 265 Writing About Windows, Dialog Boxes, and Menus 269 Writing About the Web 272
Chapter 16: Using Wikis for Documentation 287 Wikis and Collaboration 287 Value of Publications Expertise for Wikis 288 Wiki Organization and Navigation Guidelines 289 Writing for Wikis 290 Wiki Visual Design Guidelines 291
Chapter 17: Glossary Guidelines 293 Glossary Content 293 Terms for an International Audience 295 When to Include a Glossary 295 Writing Good Glossary Entries 296
Chapter 18: Indexing 301 What Is an Index? 301 Style and Format for Indexes 302 Creating an Index 305 Refining and Checking an Index 321 Checking the Size of an Index 328 Global Index 328 Online Index 329
Appendix A: Developing a Publications Department 331 Establishing a Publications Department 332 Scheduling 339 Documentation Process 341 Internationalization and Globalization 350 Online Documentation Considerations 351 Final Print Production 354 Post-Production Considerations 357
Appendix B: General Term Usage 361
Appendix C: Typographic Conventions 403
Appendix D: Checklists and Forms 411 Manuscript Tracking Chart 412 Request for Editing Form 413 Artwork Request Form 414 Technical Review Cover Letter 415 Print Specification 416
Appendix E: Recommended Reading 419 Desktop Publishing and Document Design 420 Editing Standards 421 Graphics and Illustration 421 HTML 422 Indexing 422 Information Mapping 423 Internationalization and Localization 423 Legal Issues 424 Online Help 424 Online Writing Style 424 Platform Style Guides 425 Printing 426 Project Management 426 Reference Works 427 SGML and XML 428 Typography 429 Usability Testing 429 User Interfaces 429 Web and Internet Publishing 431 Wikis, Blogs, and Social Media 432 Writing Standards 432 Writing Standards for Technical Writing 433