Developing Quality Technical Information: A Handbook for Writers and Editors

Gretchen Hargis

Michelle Carey

Ann Kilty Hernandez

Polly Hughes

Deirdre Longo

Shannon Rouiller

Elizabeth Wilde

Prentice Hall

Upper Saddle River, New Jersey 07458

www.phptr.com

The authors and publisher have taken care in the preparation of this book, but make no expressed or implied warranty of any kind and assume no responsibility for errors or omissions. No liability is assumed for incidental or consequential damages in connection with or arising out of the use of the information or programs contained herein.

© Copyright 2004 by International Business Machines Corporation. All rights reserved.

Note to U.S. Government Users: Documentation related to restricted right. Use, duplication, or disclosure is subject to restrictions set forth in GSA ADP Schedule Contract with IBM Corporation.

IBM Press Program Managers: Tara Woodman, Ellice Uffer

IBM Press Consulting Editor: Susan Visser

Cover design: Talar Boorujy

Published by Pearson plc

Publishing as IBM Press

Library of Congress Cataloging-in-Publication Data is on file with the Library of Congress

IBM Press offers excellent discounts on this book when ordered in quantity for bulk purchases or special sales, which may include electronic versions and/or custom covers and content particular to your business, training goals, marketing focus, and branding interests. For more information, please contact:

    U.S. Corporate and Government Sales
    1-800-382-3419
    corpsales@pearsontechgroup.com.

For sales outside the U.S., please contact:

    International Sales
    international@pearsoned.com.

The following terms are trademarks or registered trademarks of International Business Machines Corporation in the United States, other countries, or both: DB2, Lotus, Tivoli, WebSphere, Rational, IBM, the IBM logo, and IBM Press. Java and all Java-based trademarks are trademarks of Sun Microsystems, Inc., in the United States, other countries, or both. Microsoft, Windows, Windows NT, and the Windows logo are trademarks of the Microsoft Corporation in the United States, other countries, or both. Linux is a registered trademark of Linus Torvalds. Intel, Intel Inside (logo), MMX, and Pentium are trademarks of Intel Corporation in the United States, other countries, or both. OSF/1 and UNIX are registered trademarks and The Open Group is a trademark of the The Open Group in the United States and other countries. Other company, product, or service names mentioned herein may be trademarks or service marks their respective owners.

All rights reserved. This publication is protected by copyright, and permission must be obtained from the publisher prior to any prohibited reproduction, storage in a retrieval system, or transmission in any form or by any means, electronic, mechanical, photocopying, recording, or likewise. For information regarding permissions, write to:

    Pearson Education, Inc.
    Rights and Contracts Department
    501 Boylston Street, Suite 900
    Boston, MA 02116
    Fax: (617)-671-3447

ISBN 0-13-147749-8

Text printed in the United States on recycled paper at Courier in Westford Massachusetts.

Sixth printing, October 2008

Welcome

Many books about technical writing tell you how to develop different parts of technical information, such as headings, lists, tables, and indexes. Instead, we organized this book to tell you how to apply quality characteristics that, in our experience, make technical information easy to use, easy to understand, and easy to find. We hope you will find our approach useful and comprehensive—and we hope that you will find the information in this book easy to use, easy to understand, and easy to find!

Is this book for you?

If you are a writer, editor, or reviewer of technical information—yes! If you write, edit, or review software information, this book might be of even more interest to you because most of the examples in it come from the domain of software. However, the quality characteristics and guidelines apply to all technical information.

Reviewers can be any of the many people who are involved in developing technical information:

Acknowledgments

The previous edition of this book (1998) came out 12 years after the edition before it (1986). Our acknowledgments for the 1998 edition mentioned over 50 people who had directly or indirectly contributed to that book in the intervening years. Now, five years later, our list is much shorter, but we would still like to acknowledge the contributors to this book's predecessor, Producing Quality Technical Information: the lead writer Morris Dean and the writers, editors, and designers who worked with him—Dewey Beaudette, Fred Bethke, the late Bill Calhoun, Polly Hughes, John Hurd, Terese Johnson, Kacy Keene, Lori Neumann, and Linda Stout. Producing Quality Technical Information was also recognized as a classic in technical communication by the Journal of Computer Documentation (August 2002).

For this edition, we thought that the work would go quickly. After all, we had only to bring in changes since 1998. Nevertheless, life itself was much less accommodating for this revision. Many of the writers experienced major joys and sorrows, which take priority over even a revision schedule for a book: a marriage, two births, two deaths, a divorce, and life-threatening illnesses, not to mention the increased pressures of work.