"Clear content and consistent style are essential for the usability of any system. If you're doing something complex, describing it simply becomes that much more important. 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
"The third edition of Read Me First! A Style Guide for the Computer Industry has all the excellent content of the first editions and more. The new chapters provide insights to new forms of communication. They include sound advice on writing alternative text for illustrations, writing narrations for screencasts, and working with wikis to enhance and manage content contributed by the user community. The material on writing procedures is invaluable for those who are struggling with task-oriented information. 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.
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.
Product Description
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
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.
Backcover
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
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.
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 &
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 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.
Jakob Nielsen
Principal, Nielsen Norman Group
Author, Eyetracking Web Usability
"The third edition of Read Me First! A Style Guide for the Computer Industry has all the excellent content of the first editions and more. The new chapters provide insights to new forms of communication. They include sound advice on writing alternative text for illustrations, writing narrations for screencasts, and working with wikis to enhance and manage content contributed by the user community. The material on writing procedures is invaluable for those who are struggling with task-oriented information. 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.
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.
Product Description
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
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.
Backcover
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
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.
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 &
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 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.