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
The Members of Sun Technical Publications are award-winning senior editors and writers for Sun Microsystems, Inc.
“The third edition of Read Me First! A Style Guide for the Computer
Industry has all the excellent content of the previous editions and
more. If you need to understand the best practices for developing
useful and usable text, start with this volume. It brings together
a wealth of knowledge that all technical communication
professionals must have to succeed.”
-—Dr. JoAnn T. Hackos, President, Comtech Services, Inc.
“Clear content and consistent style are essential for the usability
of any system. Read Me First! A Style Guide for the Computer
Industry tells you how to achieve these elusive goals, and does so
following its own advice: It’s clear, consistent, and presents
advanced topics in an actionable and approachable manner.”
-—Jakob Nielsen, Principal, Nielsen Norman Group; Author,
Eyetracking Web Usability
Ask a Question About this Product More... |