Michelle Carey - Dita Best Practices: A Roadmap for Writing, Editing, and Architecting in Dita

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

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

International Sales

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

Preface

,

, , and, , and
and

Include Topics in a DITA Map

Define Relationships Between Topics

Structure Content in a DITA Map

Group Topics Regardless of Hierarchy

Related Link Element

Improving Retrievability by Applying Metadata to Topics and DITA Maps

A single page could never express our gratitude to the family, friends, and colleagues who contributed to this effort. But were not quitters, so well attempt to thank everyone who made this book possible.

We appreciate the camaraderie and support from the DITA community. The user groups, forums, and conferences have helped to shape our DITA knowledge. We want our peers and colleagues to understand how valuable they have been.

We are fortunate to have such leaders in the DITA community as reviewers: Thank you to Don Day, chair of the OASIS DITA Technical Committee, for taking the time to be one of our reviewers. Your DITA knowledge is vast and we appreciate the help. Thank you to Yas Etessam for lending us your detailed technical knowledge of DITA and your experience leading DITA implementations at such diverse companies. Amber Swope brought a more complete view for converting content to DITA. Heather Crognale is the best kind of friend, the one who reviews your manuscript and still sends you a Christmas card. Because of her years of experience as a DITA editor and her eagle eye as a copy editor, she has helped others to become DITA editors. Evelyn Eldridge is already a fan of editing in DITA, and her contribution to this book will spread the enthusiasm.

Thank you to Rob Lee for designing the icons. Without his contribution, we would never have known that teal is the new in color.

We would also like to thank Janine Trakhtenberg and Just Systems whose XMetaL authoring tool we used to produce the sample DITA files and book examples.

Of course, no book would be worth the reading if that book werent given a good working over by editors. Good editors simply make writers look better. So thank you to Shannon Rouiller, who provided expert advice on short descriptions, topic-based writing, and other chapters. Shannons thoughtful and kind advice helped us turn rough drafts into coherent information. Thanks to Elizabeth Wilde who showed us a new direction for the topic-based writing chapters and helped us dig deeper to find better examples, better tone, and better organization. And thanks to Marianne White, who helped us improve the consistency of our terminology, improve our examples, catch all those embarrassing nits, and improve the flow of the chapters.

Finally, a special thanks to our families and friends. Itll take a lot more than a few words to make up for all the late nights, the missed weekends together, and the constant dinner conversation about the default behavior of related links. Throughout this effort, our families and friends have become unwitting DITA experts. Despite the fact that knowing DITA is a very marketable skill, we realize that they put up with quite a lot. Their support, encouragement, and steady supply of caffeine made all the difference.

Laura Bellamy is an Information Architect at VMware, Inc. and a technical communications instructor at University of California Santa Cruz Extension. Laura has been a long-time DITA champion, working at IBM during the adoption and proliferation of DITA. Throughout her career she has worked on many facets of DITA implementation and now dreams in XML.

Michelle Carey is a technical editor at IBM and a technical communications instructor at University of California Santa Cruz Extension. Michelle has taught IBM teams and users groups about best practices for authoring in DITA, topic-based writing, writing for translation, editing user interfaces, and writing effective error messages. She is also a coauthor of the book