Preface
Mechanics of Writing
Capitalization
What to Capitalize
What Not to Capitalize
Contractions
Gerunds and Participles
Numbers and Numerals
Spelling Out Numbers
Using Numerals
Punctuating Numbers and Numerals
Using Fractions
Pronouns
Technical Abbreviations Acronyms and Units of Measurement
Abbreviations and Acronyms
Units of Measurement Punctuation
Apostrophe
Brackets
Colon
Comma
Dash (Em Dash)
Dash (En Dash)
Ellipsis Points
Exclamation Point
Hyphen Parentheses Period
Quotation Marks Semicolon Slash
Constructing Text
Headings
Writing Section Headings
Using Fonts in Headings
Capitalizing and Punctuating Headings
Numbering Section Headings Lists
Introducing Lists
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 Part Dividers Typographic Conventions
ead Me Firsti
Key Name Conventions Referring to Keys Documenting Multiple Keystrokes
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 Clauses and Nonrestrictlve Clauses
Write Concise Paragraphs Writing for the Reader
Make Decisions for the Reader
Anticipate the Reader\'s Questions Style That Could Offend the Reader
Avoid Humor
Avoid Sexist Language
Respect the Reader Common Writing Problems to Avoid
Anthropomorphisms
Commands as Verbs
Redundancies Ways to Improve Your Style
Study Good Writing
Work With an Editor
Attend Classes and Training
Online Writing Style
About These Guidelines Solving Online Writing Problems
Con
Creating an Effective Document Structure
Use an Easy-to-Follow Meaningful Structure
Organize Text by Hierarchy
Organize Text by Inverted Pyramid
Organize Text by Table
Organize Text by Flow Diagram
Organize Text by Task Map Writing Short Self-Contained Topics
Divide Text Into Self-Contained Linked Topics
Focus on the Structure of Content Constructing Scannable Paragraphs Headings and Lists
Write Clearly and Simply
Keep Paragraphs Short
Eliminate Unnecessary Material
Condense Text Carefully
Write Meaningful Headings and Subheadings
Use Bulleted Lists
Use Jump Lists Preserving Context in Online Documents
Make Few Assumptions About Reading Order
Offer Contextual Cues
Give the Precise Location of Related Information
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 Writing 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
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 Information
Organize Related Optional and Conditional Tasks
Use Continuous Prose Writing Procedures
Write Procedures That Are Easy to Follow
Place Procedures Appropriately
Use Procedure Headings Appropriately
Use One Method in a Single Procedure Writing Steps
Number the Steps
Make Each Step Short and Equivalent to One Action
Write Each Step as a Complete Sentence
Write Meaningful Steps
Use Branching of Steps Appropriately
Signs of Structural Problems
Writing for an International Audience
General 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
Contents
Definitions and Word Choice
Avoid Jargon and Slang
Use Terms Consistently
Avoid Abbreviations Acronyms and 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
Legal Guidelines
Copyrights
General Copyright Information
What Should You Copyright?
Copyright Notice
Third-Party Copyrighted Information Trademarks
Trademark Terms
Proper Use of Trademarks
Proper Use of Third-Party Trademarks Third-Party Web Site References
Determining Which Third-Party Site to Reference
Determining Whi ch Third-Party URL to Use
Adding a Disclaimer and Required Third-Party Wording
Preventing Unapproved References to Third-Party Sites Protection of Proprietary/Confidential Information
Identifying Proprietary/Confidential Information
Protecting Proprietary/Confidential Documents
I Me First!
Protecting Electronic Communication
Protecting Information That Appears in Examples
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
Installation Guides
System Overview Guides
User\'s Guides
Service Manuals
Configuration Guides Types of Software Manuals
Installation Guides
Programmer\'s Guides
System Administration Guides
Cor
User\'s Guides
Reference Guides Other Product Documents
White Papers
Online Help
CD Text
Release Notes and Product Notes
Demos Training Documents
Student Guides and Instructor Guides
Other Training Documents
Working With an Editor
Technical Editor\'s Role
Editor\'s Role in Producing Online Documents
Types of Editing
Developmental Editing
Copy Editing
Proofreading Edit Schedules Document Submission Editing Marks Edit Style Sheet
Editorial Style Sheet
Working With Illustrations
Working With an Illustrator
Illustration Standards and Processes When to Contact an Illustrator Submitting an Illustration Request
Illustration Formats Styles and Types Illustration Formats Illustration Styles Illustration Types
Examples of Illustrations Diagrams Online Graphics Line Art
Screen Captures
Composites
Photographs
-D Animations
Web 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
Writing About Graphical User Interfaces
Using GUI Terminology
Writing About GUIs
Writing About Mouse Actions
Using Common GUI Verbs Writing About Windows Dialog Boxes and Menus
Window Elements
Window Controls
Dialog Boxes
Menus Writing About the Web
Web Terminology
Referencing URLs
Contents
Glossary Guidelines
Glossary Content
Finding Definitions
Creating New Terms
Formatting a Glossary Terms for an International Audience When to Include a Glossary Writing Good Glossary Entries
Introducing Glossary Entries in Text
Wording a Glossary Entry
Alphabetizing a Glossary
Creating Online Links
Indexing Glossary Terms
Indexing
What Is an Index? Style and Format
Nested Entries
Page Number Style
Special Typography
"See" and "See Also" References
Capitalization
Punctuation Creating an Index
Time Required to Create an Index
Deciding Which Parts of a Document to Index
Selecting Topics to Index
Describing a Topic
Double-Posting Entries
Creating "See" and "See Also" References
Avoiding Indexing Problems Refining and Checking an Index
Spelling
Differences in Wording
Misused Singular Forms and Plural Forms
Effective Double-Posting
Number of Page References for Entries
First!
Proper Topic Cross-References "See" and "See Also" References Bad Page and Column Breaks Secondary Entries
Checking the Size of the Index
Global Index
Formatting a Global Index Editing a Global Index
Online Index
Developing a Publications Department
Establishment of a Publications Department
Establishing the Value of the Department
Funding the Publications Department
Determining the Roles of the Publications Team
Deciding on Contract or Permanent Staff Scheduling
Estimating Task Times
Developing a Project Schedule Documentation Process
Writing a Documentation Plan
Coordinating With Product Development
Writing Process
Editing Process
Illustration and Graphics Design
Technical Review Internationalization and Localization Online Documentation Considerations
Writing Issues
Content Issues
Management Issues Final Print Production
Deciding on a Strategy
Printing Methods
Binding Methods
Packaging
Working With Outside Vendors
Contents
Post-Production Considerations
Handling Post-Production Revisions Maintaining Project Continuity
B Checklists and Forms
Manuscript Tracking Chart Request for Editing Form Artwork Request Form Technical Review Cover Letter Authorization to Produce Document Print Specification
C Correct Usage of Terms
D Recommended Reading
Desktop Publishing and Document Design
Editing Standards
Graphics and Illustration
HTML and XML
Indexing
Information Mapping
Internationalization and Localization
Legal Issues
Online Help
Online Writing Style
Platform Style Guides
Printing
Project Management
Reference Works
Standard Generalized Markup Language (SGML)
Typography
Usability Testing
User Interfaces
Web and Internet Publishing
Writing Standards
Writing Standards for Technical Writing
Index