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

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

by Sun Technical Publications
Released May 2003
Publisher(s): Pearson
ISBN: 0131428993

Read it now on the O’Reilly learning platform with a 10-day free trial.

O’Reilly members get unlimited access to books, live events, courses curated by job role, and more from O’Reilly and nearly 200 top publishers.

Start your free trial

Book description

The must-have reference for every technical writer, editor, and documentation manager—now fully updated!

Read Me First! is the definitive guide to creating technical documentation that is clear, consistent, and easy to understand. Sun Microsystems' award-winning technical writers and editors cover everything from grammar to clarity, illustrations to workflow. This fully revised second edition reflects dramatic changes in the production and delivery of technical documentation. Coverage includes:

  • Detailed grammar, punctuation, typographic, and legal guidelines

  • Extensive guidance on creating effective step-by-step procedures

  • Techniques for documenting Web applications and graphical user interfaces

  • Expert help with creating indexes and glossaries

  • Extensive recommendations for using hyperlinks

  • Checklists and forms for editing, tracking manuscripts, and verifying production status

  • Guidelines for using commonly confused words and terms

  • Practical tips for gender-neutral writing

  • Internationalization guidelines that simplify translation and improve clarity for non-native English speakers

  • Real-world help for managers: hiring writers, working with illustrators, managing schedules and workflow, coordinating with printers, and more

  • Expanded and updated recommended reading list

    •

    Table of contents

    1. Copyright
    2. Tables
    3. Examples
    4. Preface
      1. How This Book Is Organized
      2. Changes for This Revision
      3. Acknowledgments
    5. 1. Mechanics of Writing
      1. Capitalization
        1. What to Capitalize
        2. What Not to Capitalize
      2. Contractions
      3. Gerunds and Participles
      4. Numbers and Numerals
        1. Spelling Out Numbers
        2. Using Numerals
        3. Punctuating Numbers and Numerals
        4. Using Fractions
      5. Pronouns
      6. Technical Abbreviations, Acronyms, and Units of Measurement
        1. Abbreviations and Acronyms
          1. Basic Guidelines for Abbreviations and Acronyms
          2. Punctuating Abbreviations and Acronyms
        2. Units of Measurement
      7. Punctuation
        1. Apostrophe
        2. Brackets
        3. Colon
          1. When to Use a Colon
          2. When Not to Use a Colon
        4. Comma
          1. When to Use a Comma
          2. When Not to Use a Comma
        5. Dash (Em Dash)
        6. Dash (En Dash)
        7. Ellipsis Points
        8. Exclamation Point
        9. Hyphen
          1. When to Use a Hyphen
          2. When Not to Use a Hyphen
        10. Parentheses
          1. When to Use Parentheses
        11. Period
        12. Quotation Marks
        13. Semicolon
        14. Slash
    6. 2. Constructing Text
      1. Headings
        1. Writing Section Headings
        2. Using Fonts in Headings
        3. Capitalizing and Punctuating Headings
        4. Numbering Section Headings
      2. Lists
        1. Introducing Lists
          1. List Introduction Guidelines
          2. List Introductions and Verbs
        2. Capitalizing and Punctuating Lists
        3. Writing Bulleted Lists
        4. Writing Numbered Lists
        5. Writing Jump Lists
      3. Tables
        1. Writing Text for Tables
          1. Table Introductions
          2. Table Captions
          3. Table Column Headings
          4. Table Text
        2. Determining the Type of Table to Use
      4. Code Examples
      5. Error Messages
      6. Cross-References
        1. Formatting Cross-References
        2. Writing Cross-References
      7. Endnotes, Footnotes, and Bibliographies
        1. Writing Endnotes and Footnotes
        2. Writing Bibliographies
          1. Citing Books
          2. Citing Articles
          3. Formatting Bibliographies
          4. Citing Electronic Sources
          5. Formatting Electronic Sources
      8. Notes, Cautions, and Tips
        1. Writing Notes
        2. Writing Cautions
        3. Writing Tips
      9. Part Dividers
      10. Typographic Conventions
      11. Key Name Conventions
        1. Referring to Keys
        2. Documenting Multiple Keystrokes
    7. 3. Writing Style
      1. Why Is Style Important?
      2. Stylistic Principles
        1. Write Simply, Directly, and Accurately
        2. Be Consistent
      3. Some Basic Elements of Style
        1. Avoid Jargon
        2. Use Active Voice and Passive Voice Appropriately
        3. Use Present Tense and Future Tense Appropriately
        4. Use Sentence Structures That Enhance Understanding
          1. Avoid Complex, Conjoined Sentences
          2. Separate Independent Clauses Appropriately
          3. Limit Subordinate Clauses
          4. Use Positive Constructions
          5. Use Parallel Structure
        5. Differentiate Between Restrictive Clauses and Nonrestrictive Clauses
        6. Write Concise Paragraphs
      4. Writing for the Reader
        1. Make Decisions for the Reader
        2. Anticipate the Reader’s Questions
          1. Anticipate Questions
          2. Use Cross-References to Address Anticipated Questions
      5. Style That Could Offend the Reader
        1. Avoid Humor
        2. Avoid Sexist Language
          1. Use Acceptable Methods to Achieve Common Gender
          2. Avoid Unacceptable Methods to Achieve Common Gender
        3. Respect the Reader
      6. Common Writing Problems to Avoid
        1. Anthropomorphisms
        2. Commands as Verbs
        3. Redundancies
      7. Ways to Improve Your Style
        1. Study Good Writing
        2. Work With an Editor
        3. Attend Classes and Training
    8. 4. Online Writing Style
      1. About These Guidelines
      2. Solving Online Writing Problems
      3. Creating an Effective Document Structure
        1. Use an Easy-to-Follow, Meaningful Structure
        2. Organize Text by Hierarchy
        3. Organize Text by Inverted Pyramid
        4. Organize Text by Table
        5. Organize Text by Flow Diagram
        6. Organize Text by Task Map
      4. Writing Short, Self-Contained Topics
        1. Divide Text Into Self-Contained, Linked Topics
        2. Focus on the Structure of Content
      5. Constructing Scannable Paragraphs, Headings, and Lists
        1. Write Clearly and Simply
        2. Keep Paragraphs Short
        3. Eliminate Unnecessary Material
        4. Condense Text Carefully
        5. Write Meaningful Headings and Subheadings
        6. Use Bulleted Lists
        7. Use Jump Lists
      6. Preserving Context in Online Documents
        1. Make Few Assumptions About Reading Order
        2. Offer Contextual Cues
        3. Give the Precise Location of Related Information
    9. 5. Constructing Links
      1. About These Guidelines
      2. Where to Place Links
      3. General Linking Strategies
        1. Avoid Overlinking
          1. Avoid Interrupting Readers
          2. Do Not Link the Same Text Repeatedly
          3. Minimize the Number of Clicks
          4. Limit Internal Linking
        2. Prevent Reader Disorientation
        3. Include Links That Answer the Reader’s Questions
        4. Use Links to Make Text Seem Shorter
        5. Provide Links in a List
        6. Place Links at the End of a Topic
        7. Provide URLs Only When Needed
        8. Test the Validity of Links
      4. Guidelines for Writing Link Text
        1. Provide Context in Link Text and Surrounding Text
        2. Weave Link Text Into Sentence Structure
        3. Choose Key Words or Phrases for Link Text
        4. Choose an Appropriate Length for Link Text
        5. Write Scannable Link Text
        6. Make Link Text Conceptually Similar to Titles or Headings
        7. Do Not Use Quotation Marks Around Link Text
    10. 6. Writing Tasks, Procedures, and Steps
      1. Understanding the Relationship Among Tasks, Procedures, and Steps
      2. Developing Task Information
        1. Perform an Audience Analysis and a User Task Analysis
        2. Provide Only Necessary Information
          1. Including Prerequisites
          2. Providing Examples
        3. Organize Related, Optional, and Conditional Tasks
          1. Using Jump Lists to Organize Tasks
          2. Using Task Maps to Organize Tasks
          3. Using Flow Diagrams to Organize Tasks
        4. Use Continuous Prose
      3. Writing Procedures
        1. Write Procedures That Are Easy to Follow
        2. Place Procedures Appropriately
        3. Use Procedure Headings Appropriately
        4. Use One Method in a Single Procedure
      4. Writing Steps
        1. Number the Steps
        2. Make Each Step Short and Equivalent to One Action
        3. Write Each Step as a Complete Sentence
        4. Write Meaningful Steps
        5. Use Branching of Steps Appropriately
        6. Signs of Structural Problems
          1. Duplicate Sets of Steps
          2. Nearly Identical Procedures
          3. Procedures With More Than 10 Steps
          4. Several Single-Step Procedures
    11. 7. Writing for an International Audience
      1. General Guidelines for Writing for Translation
      2. Cultural and Geographic Sensitivity
        1. Use Culturally Neutral Examples
        2. Include International Date, Time, and Contact Information
        3. Avoid Informal Language and Styles
      3. Definitions and Word Choice
        1. Avoid Jargon and Slang
        2. Use Terms Consistently
        3. Avoid Abbreviations, Acronyms, and Contractions
      4. Grammar and Word Usage
        1. Follow These Grammar Guidelines
        2. Use Words Precisely
        3. Use Modifiers and Nouns Carefully
        4. Limit the Use of Pronouns
        5. Simplify Sentences
      5. Numbers, Symbols, and Punctuation
        1. Clarify Measurements and Denominations
        2. Avoid Certain Symbols and Punctuation Marks
      6. Illustrations and Screen Captures
        1. Choose Illustrations to Communicate Internationally
        2. Create Callouts That Are Easy to Translate
        3. Use Charts and Tables
        4. Use International Illustrations, Symbols, and Examples
    12. 8. Legal Guidelines
      1. Copyrights
        1. General Copyright Information
        2. Copyright Duration
        3. Copyright Registration
        4. Copyright Compared With a Trade Secret
        5. What Should You Copyright?
        6. Copyright Notice
          1. Copyright Date for a Revised Document
        7. Third-Party Copyrighted Information
      2. Trademarks
        1. Trademark Terms
        2. Proper Use of Trademarks
          1. Trademark Symbols
          2. Trademark Symbol Placement
          3. Trademark Usage
          4. Trademarks and Appropriate Nouns
        3. Proper Use of Third-Party Trademarks
      3. Third-Party Web Site References
        1. Determining Which Third-Party Site to Reference
        2. Determining Which Third-Party URL to Use
        3. Adding a Disclaimer and Required Third-Party Wording
        4. Preventing Unapproved References to Third-Party Sites
      4. Protection of Proprietary/Confidential Information
        1. Identifying Proprietary/Confidential Information
        2. Protecting Proprietary/Confidential Documents
        3. Protecting Electronic Communication
        4. Protecting Information That Appears in Examples
    13. 9. Types of Technical Documents
      1. What Is a Documentation Set?
      2. Documentation Plans
        1. Documentation Set Plan
          1. Documentation Set Plan Template
          2. Documentation Set Revision Plan Template
        2. Document Plan
          1. Document Plan Template
          2. Document Revision Plan Template
      3. Abstracts
      4. Structure of Manuals
        1. Manuals With a Single Chapter
        2. Manuals With Multiple Chapters
      5. Descriptions of the Manual Parts
        1. Title Page
        2. Legal Notice
        3. Table of Contents
        4. List of Figures
        5. List of Tables
        6. List of Examples
        7. Preface
        8. Chapters
        9. Part Dividers
        10. Appendixes
        11. Glossary
        12. Bibliography
        13. Index
      6. Types of Hardware Manuals
        1. Installation Guides
        2. System Overview Guides
        3. User’s Guides
        4. Service Manuals
        5. Configuration Guides
      7. Types of Software Manuals
        1. Installation Guides
        2. Programmer’s Guides
        3. System Administration Guides
        4. User’s Guides
        5. Reference Guides
      8. Other Product Documents
        1. White Papers
        2. Online Help
        3. CD Text
          1. CD Faceplate Text
          2. CD Text Insert
        4. Release Notes and Product Notes
        5. Demos
      9. Training Documents
        1. Student Guides and Instructor Guides
        2. Other Training Documents
    14. 10. Working With an Editor
      1. Technical Editor’s Role
      2. Editor’s Role in Producing Online Documents
      3. Types of Editing
        1. Developmental Editing
          1. Developmental Editing Checklist
            1. Structure and Organization
            2. Writing
            3. Style
            4. Formatting and Layout
            5. Illustrations
            6. New Elements
        2. Copy Editing
          1. Copy Editing Checklist
            1. Readability
            2. Style
            3. Transitions
            4. Grammar
            5. Punctuation, Capitalization, and Spelling
            6. Mechanics
            7. Formatting and Layout
            8. Illustrations
        3. Proofreading
          1. Proofreading Checklist
            1. Front Matter
            2. Back Matter
            3. Grammar
            4. Punctuation, Capitalization, and Spelling
            5. Mechanics
            6. Formatting and Layout
            7. Illustrations
      4. Edit Schedules
      5. Document Submission
      6. Editing Marks
      7. Edit Style Sheet
        1. Editorial Style Sheet
    15. 11. Working With Illustrations
      1. Working With an Illustrator
        1. Illustration Standards and Processes
        2. When to Contact an Illustrator
        3. Submitting an Illustration Request
      2. Illustration Formats, Styles, and Types
        1. Illustration Formats
          1. Vector Graphics
          2. Raster Images
        2. Illustration Styles
        3. Illustration Types
      3. Examples of Illustrations
        1. Diagrams
        2. Online Graphics
        3. Line Art
        4. Screen Captures
        5. Composites
        6. Photographs
        7. 2–D Animations
        8. Web Animations
      4. Placing Illustrations
        1. Placement in Relation to Sentences
        2. Spacing in Print
        3. Alignment in Print
        4. Online Alignment and Spacing
      5. Writing Captions for Illustrations
        1. When to Use Captions
        2. Guidelines for Writing Captions
      6. Writing Callouts for Illustrations
        1. Callout Style
        2. Placement of Callouts
      7. Creating Quality Screen Captures
        1. Guidelines for Creating Screen Captures
        2. Using Screen Captures as Guideposts Only
      8. Creating Leader Lines
        1. Leader Style
        2. Additional Guidelines
      9. Simplifying Online Illustrations
    16. 12. Writing About Graphical User Interfaces
      1. Using GUI Terminology
        1. Writing About GUIs
        2. Writing About Mouse Actions
        3. Using Common GUI Verbs
      2. Writing About Windows, Dialog Boxes, and Menus
        1. Window Elements
        2. Window Controls
        3. Dialog Boxes
        4. Menus
      3. Writing About the Web
        1. Web Terminology
        2. Referencing URLs
    17. 13. Glossary Guidelines
      1. Glossary Content
        1. Finding Definitions
        2. Creating New Terms
        3. Formatting a Glossary
      2. Terms for an International Audience
      3. When to Include a Glossary
      4. Writing Good Glossary Entries
        1. Introducing Glossary Entries in Text
        2. Wording a Glossary Entry
          1. Wording the Definition
            1. Defining Multiword Terms
            2. Defining Parts of Speech
            3. Creating Multiple Definitions
            4. Defining Acronyms and Abbreviations
          2. Using “See” and “See Also” References
        3. Alphabetizing a Glossary
        4. Creating Online Links
        5. Indexing Glossary Terms
    18. 14. Indexing
      1. What Is an Index?
      2. Style and Format
        1. Nested Entries
        2. Page Number Style
          1. Major Page References
          2. Page Ranges
        3. Special Typography
        4. “See” and “See Also” References
        5. Capitalization
        6. Punctuation
      3. Creating an Index
        1. Time Required to Create an Index
        2. Deciding Which Parts of a Document to Index
        3. Selecting Topics to Index
        4. Do Not Index Superfluous Entries
          1. Avoid Entries That Are Too General
          2. Include Common Industry Terminology
          3. Avoid Using Headings as Index Entries
          4. Consider Including “Commands” as a Primary Entry
          5. Describing a Topic
          6. Anticipate a Reader’s Needs
          7. Include Only Terms a Reader Is Likely to Look Up
          8. Select Proper Words for Subjects
          9. Use Gerunds
          10. Identify the Entry Type
          11. Arrange Words for Emphasis
          12. Use Plural for Main Entries
          13. Assign the Proper Font to the Entry
          14. Group Entries
          15. Create Index Entries for Cautions, Notes, and Tips
          16. Create Index Entries for Acronyms and Abbreviations
        5. Double-Posting Entries
        6. Creating “See” and “See Also” References
          1. When to Use “See” and “See Also” References
          2. How to Use “See” and “See Also” References
        7. Avoiding Indexing Problems
          1. Use a Single-Level Entry for a Single Topic
          2. Use an Adjective With a Noun as a Primary Entry
          3. Avoid a Primary Entry That Is Too General
          4. Do Not Over-Index
          5. Do Not Under-Index
          6. Alphabetize by Keyword in Subentries
          7. Alphabetize by First Letter After a Symbol
      4. Refining and Checking an Index
        1. Spelling
        2. Differences in Wording
        3. Misused Singular Forms and Plural Forms
        4. Effective Double-Posting
        5. Number of Page References for Entries
        6. Proper Topic Cross-References
        7. “See” and “See Also” References
        8. Bad Page and Column Breaks
        9. Secondary Entries
          1. Levels of Secondary Entries
          2. Redundant Secondary Entries
          3. Possible Primary Entries in Secondary Entries
          4. Possible Rearrangement
          5. Appropriately Combined Secondary Entries
          6. Secondary Entries Under More Than One Topic
          7. Secondary Entries When Using a Combined Term Separately
          8. Secondary Entries Under Various Forms of One Topic
      5. Checking the Size of the Index
      6. Global Index
        1. Formatting a Global Index
        2. Editing a Global Index
      7. Online Index
    19. A. Developing a Publications Department
      1. Establishment of a Publications Department
        1. Establishing the Value of the Department
          1. Accounting for Value Added
          2. Tracking Avoided Costs and Costs Saved
          3. Establishing Expertise
        2. Funding the Publications Department
        3. Determining the Roles of the Publications Team
          1. Manager
          2. Writing Team Leader
          3. Writer
          4. Editor
          5. Graphic Designer
          6. Illustrator
        4. Deciding on Contract or Permanent Staff
          1. Advantages of Using Contractors
          2. Disadvantages of Using Contractors
          3. Considerations When Hiring Contractors
          4. Considerations When Hiring Permanent Staff
      2. Scheduling
        1. Estimating Task Times
        2. Developing a Project Schedule
      3. Documentation Process
        1. Writing a Documentation Plan
        2. Coordinating With Product Development
        3. Writing Process
          1. First Draft
          2. Second Draft
        4. Editing Process
        5. Illustration and Graphics Design
          1. Illustration Concerns
          2. Graphics Design Process
        6. Technical Review
          1. Comment Acceptance
          2. Participants in the Technical Review
          3. Review Meeting
      4. Internationalization and Localization
      5. Online Documentation Considerations
        1. Writing Issues
        2. Content Issues
        3. Management Issues
      6. Final Print Production
        1. Deciding on a Strategy
        2. Printing Methods
          1. Offset Printing
          2. Photocopying
        3. Binding Methods
          1. Three-Ring Binders
          2. Wire-O
          3. Perfect
          4. Saddle-Stitch
        4. Packaging
        5. Working With Outside Vendors
      7. Post-Production Considerations
        1. Handling Post-Production Revisions
        2. Maintaining Project Continuity
    20. B. Checklists and Forms
      1. Manuscript Tracking Chart
      2. Request for Editing Form
      3. Artwork Request Form
      4. Technical Review Cover Letter
      5. Authorization to Produce Document
      6. Print Specification
    21. C. Correct Usage of Terms
    22. D. Recommended Reading

    Product information

    • Title: Read Me First!: A Style Guide for the Computer Industry, Second Edition
    • Author(s): Sun Technical Publications
    • Release date: May 2003
    • Publisher(s): Pearson
    • ISBN: 0131428993