Académique Documents
Professionnel Documents
Culture Documents
By: Gretchen Hargis; Michelle Carey; Ann Kilty Hernandez; Polly Hughes; Deirdre Longo; Shannon Rouiller; Elizabeth Wilde Publisher: IBM Press Pub. Date: April 06, 2004 Print ISBN-10: 0-13-147749-8 Print ISBN-13: 978-0-13-147749-0 Pages in Print Edition: 432 Amazon.com Rating: [20 Ratings] Amazon.com Reviews Subscriber Rating: [0 Ratings]
Overview
Table of Contents
Hel
Table of Contents
Copyright Welcome Acknowledgments Chapter 1. Quality technical information What is quality technical information? Using the quality characteristics to develop quality technical information Writing task, concept, and reference topics Part 1: Easy to use Chapter 2. Task orientation Write for the intended audience Present information from the user's point of view Indicate a practical reason for information Focus on real tasks, not product functions Use headings that reveal the tasks Divide tasks into discrete subtasks Provide clear, step-by-step instructions In sum Chapter 3. Accuracy Write information only when you understand it, and then verify it Keep up with technical changes Maintain consistency of all information about a subject Use tools that automate checking for accuracy Check the accuracy of references to related information In sum
Chapter 4. Completeness Cover all topics that support users' tasks, and only those topics Cover each topic in just as much detail as users need Use patterns of information to ensure proper coverage Repeat information only when users will benefit from it In sum Part 2: Easy to understand Chapter 5. Clarity Focus on the meaning Avoid ambiguity Keep elements short Write cohesively Present similar information in a similar way Use technical terms only if they are necessary and appropriate Define each term that is new to the intended audience In sum Chapter 6. Concreteness Choose examples that are appropriate for the audience and subject Use focused, realistic, accurate, up-to-date examples Make examples easy to find Make code examples easy to adapt Use scenarios to illustrate tasks and to provide overviews Set the context for examples and scenarios Relate unfamiliar information to familiar information Use general language appropriately In sum Chapter 7. Style Use correct grammar Use correct and consistent spelling Use consistent and appropriate punctuation Write with the appropriate tone Use an active style Use the appropriate mood Follow template designs and use boilerplate text Create and follow style guidelines In sum Part 3: Easy to find Chapter 8. Organization Organize information into discrete topics by type Organize tasks by order of use Organize topics for quick retrieval
Separate contextual information from other types of information Organize information consistently Provide an appropriate number of subentries for each branch Emphasize main points; subordinate secondary points Reveal how the pieces fit together In sum Chapter 9. Retrievability Facilitate navigation and search Provide a complete and consistent index Use an appropriate level of detail in the table of contents Provide helpful entry points Link appropriately Design helpful links Make linked-to information easy to find in the target topic In sum Chapter 10. Visual effectiveness Use graphics that are meaningful and appropriate Choose graphics that complement the text Use visual elements for emphasis Use visual elements logically and consistently Balance the number and placement of visual elements Use visual cues to help users find what they need Ensure that textual elements are legible Use color and shading discreetly and appropriately Ensure that all users can access the information In sum Part 4: Putting it all together Chapter 11. Applying more than one quality characteristic Applying quality characteristics to task information Applying quality characteristics to conceptual information Applying quality characteristics to reference information Applying quality characteristics to information for an international audience Applying quality characteristics to information on the Web Revising technical information Chapter 12. Reviewing, testing, and evaluating technical information Inspecting technical information Testing information for usability Testing technical information Editing and evaluating technical information Reviewing the visual elements Part 5: Appendixes Appendix A. Quality checklist
Appendix B. Who checks which quality characteristics? Appendix C. Quality characteristics and elements Looking at the quality characteristics Looking at the elements Resources and references Easy to use Easy to understand Easy to find Putting it all together Glossary A B C D E F G H I J L M N O P Q R S T U V W About the authors Index
No part of any chapter or book may be reproduced or transmitted in any form by any means without the prior written permission for reprints and excerpts from the publisher of the book or chapter. Redistribution or other use that violates the fair use privilege under U.S. copyright laws (see 17 USC107) or that otherwise violates these Terms of Service is strictly prohibited. Violators will be prosecuted to the full extent of U.S. Federal and Massachusetts laws.
Copyright
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 Text printed in the United States on recycled paper at Courier in Westford Massachusetts. Sixth printing, October 2008
No part of any chapter or book may be reproduced or transmitted in any form by any means without the prior written permission for reprints and excerpts from the publisher of the book or chapter. Redistribution or other use that violates the fair use privilege under U.S. copyright laws (see 17 USC107) or that otherwise violates these Terms of Service is strictly prohibited. Violators will be prosecuted to the full extent of U.S. Federal and Massachusetts laws.
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 comprehensiveand we hope that you will find the information in this book easy to use, easy to understand, and easy to find!