DITA Best Practices A Roadmap for Writing, Editing, and Architecting in DITA Laura Bellamy, Michelle Carey, and Jenifer Schlotfeldt IBM Press Pearson plc Upper Saddle River, NJ • Boston • Indianapolis • San Francisco New York • Toronto • Montreal • London • Munich • Paris • Madrid Cape Town • Sydney • Tokyo • Singapore • Mexico City ibmpressbooks.com The author 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 2012 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: Steven M. Stansel, Ellice Uffer Cover design: IBM Corporation Editor in Chief: Bernard Goodwin Marketing Manager: Stephane Nakib Publicist: Heather Fox Acquisitions Editor: Bernard Goodwin Managing Editor: Kristy Hart Designer: Alan Clements Senior Project Editor: Lori Lyons Copy Editor: Apostrophe Editing Services Proofreader: Williams Woods Publishing Services Manufacturing Buyer: Dan Uhrig Published by Pearson plc Publishing as IBM Press 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 [email protected] For sales outside the U.S., please contact: International Sales [email protected] The following terms are trademarks or registered trademarks of International Business Machines Corporation in the United States, other countries, or both: IBM, IBM Press, Lotus and Notes. UNIX is a registered trademark of The Open Group in the United States and other countries or both. Linux is a registered trademark of Linus Torvalds in the United States, other countries, or both. Microsoft, Windows, SharePoint and the Windows logo are trademarks of Microsoft Corporation in the United States, other countries, or both. Java and all Java-based trademarks and logos are trademarks or registered trademarks of Oracle and/or its affiliates Adobe, the Adobe logo, FrameMaker, InDesign, PhotoShop and Illustrator are either registered trademarks or trademarks of Adobe Systems Incorporated in the United States, and/or other countries. Other company, product, or service names may be trademarks or service marks of others. 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-13: 978-0-13-248052-9 ISBN-10: 0-13-248052-2 First printing August 2011 Contents at a Glance Preface Acknowledgments About the Authors Introduction PART I: WRITING IN DITA Chapter 1 Topic-Based Writing in DITA Chapter 2 Task Topics Chapter 3 Concept Topics Chapter 4 Reference Topics Chapter 5 Short Descriptions PART II: ARCHITECTING CONTENT Chapter 6 DITA Maps and Navigation Chapter 7 Linking Chapter 8 Metadata Chapter 9 Conditional Processing Chapter 10 Content Reuse PART III: CONVERTING AND EDITING Chapter 11 Converting Content to DITA Chapter 12 DITA Code Editing Chapter 13 Content Editing Contents Preface Acknowledgments About the Author Introduction Part I: Writing in DITA Chapter 1 Topic-Based Writing in DITA Books, Topics, and Webs of Information Advantages of Writing in Topics for Writing Teams DITA Topic Types Task Orientation Task Analysis Minimalist Writing To Wrap Up Topic-Based Writing Checklist Task analysis form Chapter 2 Task Topics Separate Task Information from Conceptual or Reference Information Write One Procedure per Topic Create Subtasks to Organize Long Procedures Task Components and DITA Elements Titling the Task: <title> Introducing the Task: <shortdesc> Adding More Background Information: <context> Describing Prerequisites: <prereq> Writing the Procedure: <steps> and <steps-unordered> Concluding the Task: <example>, <postreq>, and <result> To Wrap Up