Read Me First! A Style Guide for the Computer Industry [NOOK Book]

Be the first to write a review

Overview

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 ...
See more details below
Read Me First! A Style Guide for the Computer Industry

Available on NOOK devices and apps  
  • Nook Devices
  • NOOK HD/HD+ Tablet
  • NOOK
  • NOOK Color
  • NOOK Tablet
  • Tablet/Phone
  • NOOK for Windows 8 Tablet
  • NOOK for iOS
  • NOOK for Android
  • NOOK Kids for iPad
  • PC/Mac
  • NOOK for Windows 8
  • NOOK for PC
  • NOOK for Mac
  • NOOK Study

Want a NOOK? Explore Now

NOOK Book (eBook)
$22.79
BN.com price
(Save 43%)$39.99 List Price

More About This Book

Overview

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.

Read More Show Less

Editorial Reviews

From the Publisher
“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

Read More Show Less

Product Details

  • ISBN-13: 9780137068500
  • Publisher: Pearson Education
  • Publication date: 12/31/2009
  • Sold by: Barnes & Noble
  • Format: eBook
  • Edition number: 3
  • Pages: 464
  • File size: 11 MB
  • Note: This product may take a few minutes to download.

Meet the Author

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

Read an Excerpt

PrefaceHow This Book Is Organized

Read Me First! is organized as described in the following paragraphs.

Chapter 1, "Mechanics of Writing," reviews basic punctuation rules and guidelines, plus other general writing rules and conventions. This chapter also notes exceptions to these rules, guidelines, and conventions.

Chapter 2, "Constructing Text," provides guidelines for tables, cross-references, headings, lists, and other text elements.

Chapter 3, "Writing Style," provides guidelines for writing in a style that facilitates effective communication.

Chapter 4, "Online Writing Style," provides guidelines for writing documentation that is intended primarily for online presentation. Some of these guidelines also apply to online help and web pages.

Chapter 5, "Constructing Links," provides guidelines for using links effectively in online documents.

Chapter 6, "Writing Tasks, Procedures, and Steps," provides guidelines for writing tasks, procedures, and steps in a procedure.

Chapter 7, "Writing for an International Audience," provides guidelines for writing material that is easily understood by readers whose first language is not English and that can be easily translated into other languages.

Chapter 8, "Legal Guidelines," provides guidelines for the proper use of copyrights, trademarks, and proprietary information.

Chapter 9, "Types of Technical Documents," describes the various parts that make up a manual and lists the order in which they appear. This chapter also describes typical types of computer documentation.

Chapter 10, "Working With an Editor," explains how writers and editors work together to produce high-quality documents.

Chapter 11,"Working With Illustrations," describes illustration formats, styles, and types. This chapter also provides guidelines for writing callouts, arranging callouts, using leader lines, and writing captions.

Chapter 12, "Writing About Graphical User Interfaces," explains how to document graphical user interfaces (GUIs). This chapter also provides specific guidelines for writing about web pages and referencing URLs.

Chapter 13, "Glossary Guidelines," explains how to create a glossary for a technical manual.

Chapter 14, "Indexing," explains how to prepare an index for a technical manual. This chapter covers issues such as selecting topics to index, style rules for creating an index, and editing the index.

Appendix A, "Developing a Publications Department," provides information about issues related to a documentation department, including topics such as scheduling, roles and responsibilities, technical review, and printing and production.

Appendix B, "Checklists and Forms," contains sample checklists and forms that you can use at various stages of documentation development, including art tracking, print authorization, and a technical review cover letter.

Appendix C, "Correct Usage of Terms," provides alternatives for terms that you should not use in technical documentation, and terms that you should avoid. This appendix also provides some guidance related to commonly confused words and terms.

Appendix D, "Recommended Reading," presents a list of books, divided by subject headings, that you might want to consult for additional information.Changes for This Revision

Since the last revision of Read Me First!, the globalization of technical products has increased, and online delivery has become a fast-growing means of delivery for technical documentation. Read Me First! has been extensively revised in response to these changes. The highlights of this revision are as follows:


  • A more logical organization of chapters
  • Addition of a chapter on online writing style
  • Addition of a chapter on constructing links
  • Addition of a chapter on writing tasks, procedures, and steps
  • Extensive revisions to the chapters that discuss the following topics:
    - Writing for an international audience
    - Legal guidelines
    - Working with illustrations
    - Writing about graphical user interfaces
  • Incorporation of guidelines for easing the translation of documents
Read More Show Less

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

Read More Show Less

Preface

Preface

How This Book Is Organized

Read Me First! is organized as described in the following paragraphs.

Chapter 1, "Mechanics of Writing," reviews basic punctuation rules and guidelines, plus other general writing rules and conventions. This chapter also notes exceptions to these rules, guidelines, and conventions.

Chapter 2, "Constructing Text," provides guidelines for tables, cross-references, headings, lists, and other text elements.

Chapter 3, "Writing Style," provides guidelines for writing in a style that facilitates effective communication.

Chapter 4, "Online Writing Style," provides guidelines for writing documentation that is intended primarily for online presentation. Some of these guidelines also apply to online help and web pages.

Chapter 5, "Constructing Links," provides guidelines for using links effectively in online documents.

Chapter 6, "Writing Tasks, Procedures, and Steps," provides guidelines for writing tasks, procedures, and steps in a procedure.

Chapter 7, "Writing for an International Audience," provides guidelines for writing material that is easily understood by readers whose first language is not English and that can be easily translated into other languages.

Chapter 8, "Legal Guidelines," provides guidelines for the proper use of copyrights, trademarks, and proprietary information.

Chapter 9, "Types of Technical Documents," describes the various parts that make up a manual and lists the order in which they appear. This chapter also describes typical types of computer documentation.

Chapter 10, "Working With an Editor," explains how writers and editors work together to produce high-qualitydocuments.

Chapter 11, "Working With Illustrations," describes illustration formats, styles, and types. This chapter also provides guidelines for writing callouts, arranging callouts, using leader lines, and writing captions.

Chapter 12, "Writing About Graphical User Interfaces," explains how to document graphical user interfaces (GUIs). This chapter also provides specific guidelines forwriting about web pages and referencing URLs.

Chapter 13, "Glossary Guidelines," explains how to create a glossary for a technical manual.

Chapter 14, "Indexing," explains how to prepare an index for a technical manual. This chapter covers issues such as selecting topics to index, style rules for creating an index, and editing the index.

Appendix A, "Developing a Publications Department," provides information aboutissues related to a documentation department, including topics such as scheduling, roles and responsibilities, technical review, and printing and production.

Appendix B, "Checklists and Forms," contains sample checklists and forms that you can use at various stages of documentation development, including art tracking, print authorization, and a technical review cover letter.

Appendix C, "Correct Usage of Terms," provides alternatives for terms that you should not use in technical documentation, and terms that you should avoid. This appendix also provides some guidance related to commonly confused words and terms.

Appendix D, "Recommended Reading," presents a list of books, divided by subject headings, that you might want to consult for additional information.

Changes for This Revision

Since the last revision of Read Me First!, the globalization of technical products has increased, and online delivery has become a fast-growing means of delivery for technical documentation. Read Me First! has been extensively revised in response to these changes. The highlights of this revision are as follows:

  • A more logical organization of chapters
  • Addition of a chapter on online writing style
  • Addition of a chapter on constructing links
  • Addition of a chapter on writing tasks, procedures, and steps
  • Extensive revisions to the chapters that discuss the following topics:
  • - Writing for an international audience
    - Legal guidelines
    - Working with illustrations
    - Writing about graphical user interfaces
  • Incorporation of guidelines for easing the translation of documents
Read More Show Less

Customer Reviews

Be the first to write a review
( 0 )
Rating Distribution

5 Star

(0)

4 Star

(0)

3 Star

(0)

2 Star

(0)

1 Star

(0)

Your Rating:

Review Guidelines
Add Recommendations
Your Name: Create a Pen Name or

Barnes & Noble.com Review Rules

Our reader reviews allow you to share your comments on titles you liked, or didn't, with others. By submitting an online review, you are representing to Barnes & Noble.com that all information contained in your review is original and accurate in all respects, and that the submission of such content by you and the posting of such content by Barnes & Noble.com does not and will not violate the rights of any third party. Please follow the rules below to help ensure that your review can be posted.

Reviews by Our Customers Under the Age of 13

We highly value and respect everyone's opinion concerning the titles we offer. However, we cannot allow persons under the age of 13 to have accounts at BN.com or to post customer reviews. Please see our Terms of Use for more details.

What to exclude from your review:

Please do not write about reviews, commentary, or information posted on the product page. If you see any errors in the information on the product page, please send us an email.

Reviews should not contain any of the following:

  • - HTML tags, profanity, obscenities, vulgarities, or comments that defame anyone
  • - Time-sensitive information such as tour dates, signings, lectures, etc.
  • - Single-word reviews. Other people will read your review to discover why you liked or didn't like the title. Be descriptive.
  • - Comments focusing on the author or that may ruin the ending for others
  • - Phone numbers, addresses, URLs
  • - Pricing and availability information or alternative ordering information
  • - Advertisements or commercial solicitation

Reminder:

  • - By submitting a review, you grant to Barnes & Noble.com and its sublicensees the royalty-free, perpetual, irrevocable right and license to use the review in accordance with the Barnes & Noble.com Terms of Use.
  • - Barnes & Noble.com reserves the right not to post any review -- particularly those that do not follow the terms and conditions of these Rules. Barnes & Noble.com also reserves the right to remove any review at any time without notice.
  • - See Terms of Use for other conditions and disclaimers.
Search for Products You'd Like to Recommend

Recommend other products that relate to your review. Just search for them below and share!

Create a Pen Name

Your Pen Name is your unique identity on BN.com. It will appear on the reviews you write and other website activities. Your Pen Name cannot be edited, changed or deleted once submitted.

 
Your Pen Name can be any combination of alphanumeric characters (plus - and _), and must be at least two characters long.

Continue Anonymously
    If you find inappropriate content, please report it to Barnes & Noble
    Why is this product inappropriate?
    Comments (optional)