Read Me First! A Style Guide for the Computer Industry, Third Edition

by Sun Technical Publications

• ISBN13: 9780137058266
• ISBN10: 0137058268
• Edition: 3rd
• Format: Paperback
• Copyright: 2009-12-17
• Publisher: Prentice Hall

Summary

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.

Author Biography

The Members of Sun Technical Publications are award-winning senior editors and writers for Sun Microsystems, Inc. 

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