Register your product to gain access to bonus material or receive a coupon.
Read Me First! A Style Guide for the Computer Industry,, 3rd Edition
- By Sun Microsystems
- Published Dec 17, 2009 by Pearson.
eBook (Watermarked)
- Sorry, this book is no longer in print.
- Includes EPUB and PDF
- About eBook Formats
This eBook includes the following formats, accessible from your Account page after purchase:
EPUB
The open industry format known for its reflowable content and usability on supported mobile devices.
PDF
The popular standard, used most often with the free Acrobat® Reader® software.
This eBook requires no passwords or activation to read. We customize your eBook by discreetly watermarking it with your name, making it uniquely yours.
Description
- Copyright 2010
- Edition: 3rd
- eBook (Watermarked)
- ISBN-10: 0-13-265064-9
- ISBN-13: 978-0-13-265064-9
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 of Read Me First 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
Sample Content
Table of Contents
Preface 21
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 4: Structuring Information 113
Organization Schemes 113
Writing Short, Self-Contained Sections 118
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 15: Creating Screencasts 275
Screencast Overview 275
Storyboard Overview 277
Writing Narration for Screencasts 278
Recording Narration 284
Screencast Review Cycle 286
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
Index 435