Technical Writing For Dummies E-Book

Sheryl Lindsell-Roberts

• Herausgeber: John Wiley & Sons
• Kategorie: Fachliteratur
• Sprache: Englisch

Seitenzahl: 336

Veröffentlichungsjahr: 2011

Beschreibung

A complete and friendly guide to technical writing! Let's face it, a lot of technical documentation reads as if it had been translated into English from Venutian by a native speaker of gibberish. Which is annoying for you and expensive for the manufacturer who pays with alienated customers and soaring technical support costs. That's why good technical writers are in such big demand worldwide. Now, Technical Writing For Dummies arms you with the skills you need to cash in on that demand. Whether you're contemplating a career as a technical writer, or you just got tapped for a technical writing project, this friendly guide is your ticket to getting your tech writing skills up to snuff. It shows you step-by-step how to: * Research and organize information for your documents * Plan your project in a technical brief * Fine-tune and polish your writing * Work collaboratively with your reviewers * Create great user manuals, awesome abstracts, and more * Write first-rate electronic documentation * Write computer- and Web-based training courses Discover how to write energized technical documents that have the impact you want on your readers. Wordsmith Sheryl Lindsell-Roberts covers all the bases, including: * All about the red-hot market for technical writing and how to get work as a technical writer * The ABCs of creating a strong technical document, including preparing a production schedule, brainstorming, outlining, drafting, editing, rewriting, testing, presentation, and more * Types of technical documents, including user manuals, abstracts, spec sheets, evaluation forms and questionnaires, executive summaries, and presentations * Writing for the Internet--covers doing research online, creating multimedia documents, developing computer-based training and Web-based training, and writing online help Combining examples, practical advice, and priceless insider tips on how to write whiz-bang technical documents, Technical Writing For Dummies is an indispensable resource for newcomers to technical writing and pros looking for new ideas to advance their careers.

Leseprobe

Technical Writing For Dummies®

by Sheryl Lindsell-Roberts

Technical Writing For Dummies®

Published byWiley Publishing, Inc.111 River St.Hoboken, NJ 07030-5774www.wiley.com

Copyright © 2001 by Wiley Publishing, Inc., Indianapolis, Indiana

Published simultaneously in Canada

No part of this publication may be reproduced, stored in a retrieval system, or transmitted in any form or by any means, electronic, mechanical, photocopying, recording, scanning, or otherwise, except as permitted under Sections 107 or 108 of the 1976 United States Copyright Act, without either the prior written permission of the Publisher, or authorization through payment of the appropriate per-copy fee to the Copyright Clearance Center, 222 Rosewood Drive, Danvers, MA 01923, 978-750-8400, fax [phone]. Requests to the Publisher for permission should be addressed to the Legal Department, Wiley Publishing, Inc., 10475 Crosspoint Blvd., Indianapolis, IN 46256, 317-572-3447, fax [phone].

Trademarks: Wiley, the Wiley Publishing logo, For Dummies, the Dummies Man logo, A Reference for the Rest of Us!, The Dummies Way, Dummies Daily, The Fun and Easy Way, Dummies.com, and related trade dress are trademarks or registered trademarks of John Wiley & Sons, Inc. and/or its affiliates in the United States and other countries and may not be used without written permission. All other trademarks are the property of their respective owners. Wiley Publishing, Inc., is not associated with any product or vendor mentioned in this book.

LIMIT OF LIABILITY/DISCLAIMER OF WARRANTY: While the publisher and author have used their best efforts in preparing this book, they make no representations or warranties with respect to the accuracy or completeness of the contents of this book and specifically disclaim any implied warranties of merchantability or fitness for a particular purpose. No warranty may be created or extended by sales representatives or written sales materials. The advice and strategies contained herein may not be suitable for your situation. You should consult with a professional where appropriate. Neither the publisher nor author shall be liable for any loss of profit or any other commercial damages, including but not limited to special, incidental, consequential, or other damages.

For general information on our other products and services or to obtain technical support, please contact our Customer Care Department within the U.S. at 877-762-2974, outside the U.S. at 317-572-3993, or fax [phone].

Wiley also publishes its books in a variety of electronic formats. Some content that appears in print may not be available in electronic books.

Library of Congress Control Number: 00-110789

ISBN: 978-0-7645-5308-0

Manufactured in the United States of America

15 14 13 12 11 10 9 8

1O/RQ/RQ/QV/IN

About the Author

I’m fortunate to have a job that would be my hobby if it weren’t my profession. I love to write. Between freelance business writing assignments and business writing seminars, I’ve written 18 books for the professional and humor markets.

Beyond that, I wear a lot of hats, just as you do. I’m a wife and the mother of two wonderful sons — Marc, an award-winning California architect, and Eric, a dedicated Maryland chiropractor. I live with my husband, Jon, in Parnassus, the incredible home in Marlborough, Massachusetts (outside of Boston), that Marc designed. However, if home is where you hang your hat, my hat is a cap of the New York Yankees.

When my life gets more complicated than it needs to be, my warm-weather nirvana is my 30-foot sailboat, Worth th’ Wait. Jon and I are on board every weekend that the temperature rises above 60° — if the seas aren’t too treacherous. (We’ve also been out there when they were too treacherous, but not by choice.) I don’t bring my suitcase stuffed with clothes because there isn’t room to put too much; I’ve learned to minimize. All I need is sunscreen, a few pairs of shorts, some T-shirts, and a good book. Columbus wanted to prove that the world was round, and Captain Kirk wanted “to boldly go where no man has gone before” — Jon and I merely want to leave our obligations and our harried lives on shore. Everyone needs a nirvana, even if it’s a spot under a tree or the corner of a room.

When I’m not writing or sailing, I travel, paint (watercolors, not walls), garden, photograph nature, read, ski, eat strawberry cheesecake, and work out at the gym (after the cheesecake, I really need to). I try to live each day to the fullest!

Sheryl Lindsell-Roberts, M.A. and T.W.E.**Technical Writer Extraordinaire

Dedication

I dedicate this book to Jon — my truly wonderful and very patient husband. Everyone needs one special person who loves them for who they are and helps them to know that dreams do come true. To me, Jon is that special person. And our boat, Worth th’ Wait, is the personification of our lives together. Jon is my anchor, and I’m the wind in his sails.

Author’s Acknowledgments

I want to express my heartfelt thanks to my family (blood and extended) and to my dear friends. Without their love and support, I wouldn’t be the person I am today — and I wouldn’t be realizing my dreams.

I want to praise all the “Dummies” (and I say that with utmost respect) who made this book a reality. This is especially true of Jill Alexander the Great, my acquisitions editor, whom I thank for her steadfastness, sound advice, and confidence in me. I also appreciate the keen insights of Suzanne Snyder, project editor; Tina Sims, senior copy editor; and Karen Callahan, technical editor. And I extend thanks to two special subject matter experts who kept me honest in several of this book’s chapters: Dr. Barry Kingsbury and Jennifer Lund.

Publisher’s Acknowledgments

We’re proud of this book; please send us your comments through our Dummies online registration form located at www.dummies.com/register/.

Some of the people who helped bring this book to market include the following:

Acquisitions, Editorial, and Media Development

Project Editor: Suzanne Snyder

Acquisitions Editor: Jill Alexander

Senior Copy Editor: Tina Sims

Acquisitions Coordinator: Lauren Cundiff

Technical Editor: Karen Callahan

Senior Permissions Editor: Carmen Krikorian

Editorial Manager: Pam Mourouzis

Editorial Assistant: Carol Strickland

Cover Photos: VCP–FPG

Composition

Project Coordinator: Nancee Reeves

Layout and Graphics: Amy Adrian, LeAndra Johnson, Jill Piscitelli, Jacque Schneider, Brian Torwelle, Jeremey Unger, Erin Zeltner

Proofreaders: Laura Albert, Andy Hollandbeck, Jennifer Mahern, Susan Moritz, Carl Pierce, Nancy Price, Marianne Santy

Indexer: Steve Rath

Special Help Dr. Barry Kingsbury, Jennifer Lund

General and Administrative

Hungry Minds, Inc.: John Kilcullen, CEO; Bill Barry, President and COO; John Ball, Executive VP, Operations & Administration; John Harris, CFO

IDG Books Technology Publishing Group: Richard Swadley, Senior Vice President and Publisher; Mary Bednarek, Vice President and Publisher; Walter R. Bruce III, Vice President and Publisher; Joseph Wikert, Vice President and Publisher; Mary C. Corder, Editorial Director; Andy Cummings, Publishing Director, General User Group; Barry Pruett, Publishing Director

IDG Books Manufacturing: Ivor Parker, Vice President, Manufacturing

IDG Books Marketing: John Helmus, Assistant Vice President, Director of Marketing

IDG Books Online Management: Brenda McLaughlin, Executive Vice President, Chief Internet Officer; Gary Millrood, Executive Vice President of Business Development, Sales and Marketing

IDG Books Packaging: Marc J. Mikulich, Vice President, Brand Strategy and Research

IDG Books Production for Branded Press: Debbie Stailey, Production Director

IDG Books Sales: Roland Elgey, Senior Vice President, Sales and Marketing; Michael Violano, Vice President, International Sales and Sub Rights

Publishing and Editorial for Consumer Dummies

Diane Graves Steele, Vice President and Publisher, Consumer Dummies

Joyce Pepple, Acquisitions Director, Consumer Dummies

Kristin A. Cocks, Product Development Director, Consumer Dummies

Michael Spring, Vice President and Publisher, Travel

Brice Gosnell, Associate Publisher, Travel

Suzanne Jannetta, Editorial Director, Travel

Publishing for Technology Dummies

Andy Cummings, Vice President and Publisher, Dummies Technology/General User

Composition Services

Gerry Fahey, Vice President of Production Services

Debbie Stailey, Director of Composition Services

Contents

Title

Introduction

Skills, Not Frills

Preview of Coming Attractions

Icons, Icons Everywhere

Author’s Note about Genders

Making This Book Your Personal Reference Source

Part I : What It Takes to Write Technical Documentation

Chapter 1: Accelerating Your Career the “Write” Way

Technical Writers Spring from All Walks of Life

Technical Writing Differs from Business Writing

Print or Electronic Media — That Is the Question

Assigning Responsibility for Technical Documents

Strategy, Not Software

What You Need to Succeed

Seeing Is Believing

Chapter 2: The Person to Whom You’re Speaking

How to Feed a Martian

Getting Jump-Started with the Technical Brief

Slicing and Dicing the Technical Brief

Part II : The Write Stuff

Chapter 3: Creating a Team and a Plan

Benefiting from the Team Experience

Kicking Off with the Technical Brief

Choosing the Medium That’s Right for Your Readers

Letting the Production Process Begin

Amassing the Brain Power

Generating an Outline

Getting Your Arms around the Document

Chapter 4: Don’t Be a Draft Dodger

Psyching Yourself Up

Getting Down to Business

Integrating the Editing Process

Revise and Consent

Chapter 5: Visualize This!

May I Have Your Attention, Please?

Using White Space

Give Me a Break

Harness the Visual Power of Headlines

Put It on the List

The Natural Order of Things

A Pixel (Picture) Is Worth a Thousand Words

Table That Thought

Go Figure

Why Is a Pink Slip Pink?

Meet Prints Charming

Scale for Size

Location, Location, Location

What’s Your Visual Preference?

Chapter 6: Going In for a Tone Up

Give ’Em a Little KISS

Using Contractions

Accentuating the Positive

Loving the Active Voice

Using Politically Correct Gender

Consistency and Clarity Count

Defining Terms

Who’s Laughing?

When to Be a Jargon Junkie

Chapter 7: Dotting the Eyes and Crossing the Tees

Don’t Turn On Your Computer and Turn Off Your Brain

The Proof Is in the Proofreaders’ Marks

Use the Editing Checklist

Part III : Types of Technical Documents

Chapter 8: The Ultimate User Manual

Get Up and Running

Assessing Your Reader

The Devil Is in the Details

Check Out the Contents of the Box

Chunking Up

Table That Procedure

Between the Covers

Testing, Testing, 1-2-3

Getting All Bound Up

Join-the-Dots Brain Teaser

Chapter 9: Writing in the Abstract

Types of Abstracts

Using Abstracts Effectively

Chapter 10: Writing Spec Sheets

The Natural Order of Things

Phase 1: Requirement Specs

Phase 2: Functional Specs

Phase 3: Design Specs

Phase 4: Test Specs

Phase 5: End-User Specs

Chapter 11: How Am I Doing? That Is the Question(naire)

Don’t Shoot the Messenger

Designing the Form

Posing the Questions

Learning from the Results

Chapter 12: I Came, I Spoke, I Conquered

Getting to Know Your Audience

Getting Ready for Prime Time

Conveying Your Message with Confidence and Competence

Choosing Appropriate Visual Aids

Giving Them Something to Remember You By

Checking Out Before Checking In

Chapter 13: Executive Sum-Upmanship

An Executive Summary Is Critical

Summarizing for the Executive

Seeing Is Believing

Part IV : Computers and More

Chapter 14: Doing_Research_Online.com

Surf’s Up

Just Browsing

Searching for the Holy Grail

Understanding Cyberbabble

Outlaws in This New Frontier

Chapter 15: Sights and Sounds

Basics of Electronic Page Design

Color My World

Graceful Graphics

Hear Ye, Hear Ye!

Am I Your Type?

So You Wanna Make a Movie

Chapter 16: Computer-Based Training (CBT)

The Role of the Writer

“C” Is for Computer-Based

“T” Is for Training

Types of Interactivity

Presenting the Learning Experience

Solving Business Problems

Platform Independence

Designing a CBT Process

Creating a Storyboard

Planning the Right Kind of CBT

Getting the Goods Out the Door

Meeting Expectations

Testing for Quality Assurance

Chapter 17: Web-Based Training: CBT on Steroids

Setting Your Sights (Or Sites)

Planning the Users’ Experience

Display the Evidence

Multimedia Madness and Frame-ups

Writing the Story and Linking It

Standard Types of Presentations

Standard Types of Interaction

Tools of the Trade

Building a Modest WBT

Calling External Programs from Your Web Page

Documenting and Archiving Sources

Quality Assurance Testing

Publishing to the Web

Chapter 18: Creating Online Help

Getting Intimate with Online Help

Getting Started

Striking a Balance

Naming Conventions

The Litmus Test

Moving a Print Document Online

Keep On Trucking

Part V : The Part of Tens

Chapter 19: Ten Ways to Make Your Technical Documents Shout “Read Me!”

“See” Your Target So You Know Where to Aim

Create Structure with Bones

Add Meat to the Bones

Make the Bones Visually Appealing

Hone the Tone

Proofread ’Til Your Eyes Pop Out

Give the Document the Litmus Test

For E-Docs Only

Chapter 20: Ten Tips for Publishing in a Technical Journal

Don’t Procrastinate; Just Do It!

Hooking Up with the Right Publication

Lurking Behind the Masthead

Understanding the Lingo

Writing a Query Letter

Simultaneous Submissions

Confidentiality

Don’t Take “No” for an Answer

Chapter 21: Ten Things to Know about Filing a Patent

Types of Patents

What’s an Invention?

He Who Hesitates Is Lost

Doing Your Homework

Submitting Your Idea

Leaving Legal Stuff to the Pros

On the Foreign Front

Chapter 22: Ten Tips for Writing a Grant Proposal

Title (Cover) Page

Table of Contents

Executive Summary

Introduction

Statement of Need

Project Description

Budget

Conclusion

Appendixes

Appendix A: Punctuation Made Easy

Commas

Colons and Semicolons

Dashes and Parentheses

Brackets

Other Punctuation

Appendix B: Grammar’s Not Grueling

Test Your Grammatical Skills

Adjectives

Adverbs

Conjunctions

Double Negatives

Nouns

Prepositions

Pronouns

Verbs

Answers to Quickie Quiz

Appendix C: Abbreviations and Metric Equivalents

Writing Abbreviations

Metric and U.S. Equivalents

Appendix D: Technical Jabberwocky

Introduction

Man is still the most extraordinary computer of all.

—John F. Kennedy, 35th U.S. President

All technical people are called upon to write technical documents at some point in their careers. Therefore, your career depends on your ability to write and present your information clearly and distinctly. So this book is for you if . . .

You’re an engineer, scientist, computer programmer, or information technology specialist.

You’re involved in any other technical field.