Read me first! : a style guide for the computer industry
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 g...
| Corporate Author: | |
|---|---|
| Other Authors: | |
| Format: | eBook |
| Language: | Inglés |
| Published: |
[Place of publication not identified]
Prentice Hall Pearson Education distributor
2010
|
| Edition: | 3rd ed |
| Subjects: | |
| See on Biblioteca Universitat Ramon Llull: | https://discovery.url.edu/permalink/34CSUC_URL/1im36ta/alma991009629007506719 |
Table of Contents:
- Cover
- Contents
- Preface
- 1 Mechanics of Writing
- Capitalization
- What to Capitalize
- What Not to Capitalize
- Contractions
- Gerunds and Participles
- Numbers and Numerals
- Punctuating Numbers and Numerals
- Using Fractions
- Pronouns
- Technical Abbreviations, Acronyms, and Units of Measurement
- Abbreviations and Acronyms
- Units of Measurement
- Punctuation
- Apostrophe
- Colon
- Comma
- Dash (Em Dash)
- Dash (En Dash)
- Ellipsis Points
- Exclamation Point
- Hyphen
- Parentheses
- Period
- Quotation Marks
- Semicolon
- Slash
- Square Brackets
- 2 Constructing Text
- Headings
- Writing Section Headings
- Using Fonts in Headings
- Capitalizing and Punctuating Headings
- Numbering Section Headings
- Lists
- List Introduction Guidelines
- List Introductions and Verbs
- Capitalizing and Punctuating Lists
- Writing Bulleted Lists
- Writing Numbered Lists
- Writing Jump Lists
- Tables
- Writing Text for Tables
- Determining the Type of Table to Use
- Code Examples
- Error Messages
- Cross-References
- Formatting Cross-References
- Writing Cross-References
- Endnotes, Footnotes, and Bibliographies
- Writing Endnotes and Footnotes
- Writing Bibliographies
- Notes, Cautions, and Tips
- Writing Notes
- Writing Cautions
- Writing Tips
- Key Name Conventions
- Referring to Keys
- Documenting Multiple Keystrokes
- Symbol Name Conventions
- 3 Writing Style
- Why Is Style Important?
- Stylistic Principles
- Write Simply, Directly, and Accurately
- Be Consistent
- Some Basic Elements of Style
- Avoid Jargon
- Use Active Voice and Passive Voice Appropriately
- Use Present Tense and Future Tense Appropriately
- Use Sentence Structures That Enhance Understanding
- Differentiate Between Restrictive Elements and Nonrestrictive Elements.
- Construct Scannable Paragraphs, Headings, and Lists
- Write Clearly and Simply
- Keep Paragraphs Short
- Eliminate Unnecessary Material
- Be Careful When Condensing Text
- Write for the Reader
- Make Decisions for the Reader
- Anticipate the Reader's Questions
- Avoid Style That Could Offend the Reader
- Avoid Humor
- Avoid Sexist Language
- Do Not Talk Down to the Reader
- Common Writing Problems to Avoid
- Anthropomorphisms
- Idioms and Colloquialisms
- Phrasal Verbs
- Commands as Verbs
- Redundancies
- 4 Structuring Information
- Organization Schemes
- Organize by Hierarchy
- Organize by Inverted Pyramid
- Organize by Table
- Organize by Flow Diagram
- Organize by Task Map
- Writing Short, Self-Contained Sections
- Divide Text Into Self-Contained Topics
- Include Transitions
- 5 Online Writing Style
- About These Guidelines
- Solving Online Writing Problems
- Creating an Effective Online Document Structure
- Writing Online Topics
- Constructing Scannable Text in Online Documents
- Preserving Context in Online Documents
- Make Few Assumptions About Reading Order
- Offer Contextual Cues
- Give the Precise Location of Related Information
- 6 Constructing Links
- About These Guidelines
- Where to Place Links
- General Linking Strategies
- Avoid Overlinking
- Prevent Reader Disorientation
- Include Links That Answer the Reader's Questions
- Use Links to Make Text Seem Shorter
- Provide Links in a List
- Place Links at the End of a Topic
- Provide URLs Only When Needed
- Test the Validity of Links
- Guidelines for Crafting Link Text
- Provide Context in Link Text and Surrounding Text
- Weave Link Text Into Sentence Structure
- Choose Key Words or Phrases for Link Text
- Choose an Appropriate Length for Link Text
- Write Scannable Link Text
- Make Link Text Conceptually Similar to Titles or Headings.
- Do Not Use Quotation Marks Around Link Text
- 7 Writing Tasks, Procedures, and Steps
- Understanding the Relationship Among Tasks, Procedures, and Steps
- Developing Task Information
- Perform an Audience Analysis and a User Task Analysis
- Provide Only Necessary Task Information
- Organize Related, Optional, and Conditional Tasks
- Use Continuous Prose for Some Tasks
- Do Not Use Procedures for Command Explanations
- Writing Procedures
- Write Procedures That Are Easy to Follow
- Place Procedures Appropriately
- Use Procedure Headings Appropriately
- Use One Method to Describe a Single Procedure
- Writing Steps
- Order and Number the Steps
- Make Each Step Short and Equivalent to One Action
- Write Each Step as a Complete Sentence in the Imperative Mood
- Write Meaningful Steps
- Use Branching of Steps Appropriately
- Checking for Structural Problems
- Duplicate Series of Steps
- Nearly Identical Procedures
- Many Nested Substeps
- Procedures With More Than 10 Steps
- Several Single-Step Procedures
- Repeated Steps Indicated at the End of Repeated Actions
- 8 Writing for an International Audience
- Guidelines for Writing for Translation
- Cultural and Geographic Sensitivity
- Use Culturally Neutral Examples
- Include International Date, Time, and Contact Information
- Avoid Informal Language and Styles
- Definitions and Word Choice
- Avoid Jargon and Slang
- Do Not Use Foreign Terms
- Use Terms Consistently
- Use Abbreviations and Acronyms Judiciously
- Avoid Contractions
- Grammar and Word Usage
- Follow These Grammar Guidelines
- Use Words Precisely
- Use Modifiers and Nouns Carefully
- Limit the Use of Pronouns
- Simplify Sentences
- Numbers, Symbols, and Punctuation
- Clarify Measurements and Denominations
- Avoid Certain Symbols and Punctuation Marks
- Illustrations and Screen Captures.
- Choose Illustrations to Communicate Internationally
- Create Callouts That Are Easy to Translate
- Use Charts and Tables
- Use International Illustrations, Symbols, and Examples
- 9 Legal Guidelines
- Understanding Copyrights
- General Copyright Information
- What Should You Copyright?
- Copyright Notice
- Third-Party Copyrighted Information
- Protecting Trademarks
- Trademark Terms
- Proper Use of Trademarks
- Proper Use of Trademarks in Online Works
- Proper Use of Third-Party Trademarks
- Referencing External Web Sites
- Pointing to Third-Party Web Sites
- Protecting Confidential Information
- Identifying Confidential Information
- Classifying and Labeling Confidential Documents
- Classifying and Labeling Confidential Electronic Communication
- Protecting Confidential Information in Examples
- 10 Types of Technical Documents
- What Is a Documentation Set?
- Documentation Plans
- Documentation Set Plan
- Document Plan
- Abstracts
- Structure of Manuals
- Manuals With a Single Chapter
- Manuals With Multiple Chapters
- Descriptions of the Manual Parts
- Title Page
- Legal Notice
- Table of Contents
- List of Figures
- List of Tables
- List of Examples
- Preface
- Chapters
- Part Dividers
- Appendixes
- Glossary
- Bibliography
- Index
- Types of Hardware Manuals
- Types of Software Manuals
- Release Notes and Product Notes
- Other Product Documents
- Training Documentation
- Student Guides and Instructor Guides
- Other Training Documents
- 11 Working With an Editor
- Technical Editor's Role
- Editor's Role in Producing Online Documents
- Types of Editing
- Developmental Editing
- Developmental Editing Guidelines
- Copy Editing
- Copy Editing Guidelines
- Proofreading
- Proofreading Guidelines
- Planning Ahead for Editing
- Submitting a Document for Editing
- Editing Marks.
- Creating a Style Sheet
- Editorial Style Sheet
- 12 Working With Illustrations
- Working With an Illustrator
- Improving Quality and Accelerating Workflow
- Contacting an Illustrator
- Submitting an Illustration Request
- Understanding Illustration Files
- Vector Images
- Raster Images
- Types of Illustrations
- Diagrams
- Line Art
- Screen Captures
- Photographs
- Animations
- Placing Illustrations
- Placement in Relation to Sentences
- Spacing in Print
- Alignment in Print
- Online Alignment and Spacing
- Writing Captions for Illustrations
- When to Use Captions
- Guidelines for Writing Captions
- Writing Callouts for Illustrations
- Callout Style
- Placement of Callouts
- Creating Quality Screen Captures
- Guidelines for Creating Screen Captures
- Using Screen Captures as Guideposts Only
- Creating Leader Lines
- Leader Style
- Additional Guidelines
- Simplifying Online Illustrations
- 13 Writing Alternative Text for Nontext Elements
- Section 508 Requirements Overview
- Assistive Technologies
- Guidelines for Meeting Section 508 Requirements
- General Guidelines for Writing Alternative Text
- Determining the Context of a Nontext Element
- Writing Short Alternative Text
- Writing Long Alternative Text
- Writing About Nontext Elements
- Simple Graphics
- Complex Graphics
- Diagrams
- Mathematical Equations
- Multimedia Content
- 14 Documenting Graphical User Interfaces
- Using GUI Terminology
- Writing About GUIs
- Writing About Mouse Actions
- Using Common GUI Terms
- Writing About Windows, Dialog Boxes, and Menus
- Window Elements
- Window Controls
- Dialog Boxes
- Menus
- Writing About the Web
- Web Terminology
- Referencing URLs
- 15 Creating Screencasts
- Screencast Overview
- Developing a Screencast
- Storyboard Overview
- Definition of Storyboard
- Developing a Storyboard.
- Writing Narration for Screencasts.
