Free Trial

Safari Books Online is a digital library providing on-demand subscription access to thousands of learning resources.

  • Create BookmarkCreate Bookmark
  • Create Note or TagCreate Note or Tag
  • PrintPrint
Share this Page URL

DITA Best Practices: A Roadmap for Writing, Editing, and Architecting in DIT...

DITA Best Practices: A Roadmap for Writing, Editing, and Architecting in DITA, Video Enhanced Edition

Laura Bellamy

Michelle Carey

Jenifer Schlotfeldt

IBM Press

Upper Saddle River, NJ Boston Indianapolis San Francisco

New York Toronto Montreal London Munich Paris Madrid

Cape Town Sydney Tokyo Singapore Mexico City

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

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.

Library of Congress Cataloging-in-Publication data is on file.

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

First printing October 2011

ISBN-13: 978-0-13-248052-9

ISBN-10: 0-13-248052-2


A single page could never express our gratitude to the family, friends, and colleagues who contributed to this effort. But we’re not quitters, so we’ll 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 weren’t 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. Shannon’s 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. It’ll 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.

About the Authors

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 Developing Quality Technical Information. Michelle loves to ride motorcycles and mountain bikes, herd cats, and diagram sentences.

Jenifer Schlotfeldt is a project leader, information developer, and technical leader at IBM and a technical communications instructor at the University of California Santa Cruz Extension. She has been authoring, testing, and teaching DITA since 2003. She has converted documentation to DITA, authored new content in DITA, contributed to new DITA specializations, and created many training materials for different facets of DITA authoring.


So, finally, you’ve decided to write your content in DITA.

First, congratulations! For most companies or organizations, deciding whether to adopt Darwin Information Typing Architecture (DITA) as an XML authoring methodology is an arduous journey. We’re strong supporters of the DITA standard and are confident that your investment to move to DITA can improve the technical information that you create for your products, services, or technologies.

Second, now what are you going to do? How do you start implementing DITA? What do you need to know before you start writing? What best practices have many of us in the technical writing community established? What are the gotchas and pitfalls of authoring in DITA? What’s the best way to learn about DITA?

Don’t panic: We’ve helped to educate many teams in our own companies and communities and promise you that learning how to semantically tag content in XML is not the hard part. Learning how to best use (or not use) the DITA elements, DITA maps, and topic types to fit your content and your organization is the real challenge.

The default DITA standard includes more than 400 elements, and those elements contain attributes. You’ll need to consider these questions before you get started:

  • Should you use all of the DITA elements and attributes?

  • Which features do you need to understand to get going?

  • Which features can you wait to implement after you’ve spent more time working with DITA?

  • What are the guidelines that you should follow?

This book is for users who have made the decision to use DITA and are looking for advice from experienced DITA authors, editors, and information architects about how to write effective technical information in DITA.

We decided to write this book to fill an information gap in the available DITA information. Some DITA books and educational courses tell you what each DITA element represents and what it is used for. However, they don’t always tell you how to best create effective content for these elements or how to organize that content.

For example, current DITA education defines what a <shortdesc> element is, but that education doesn’t show you how to write effective text to go in that element.

We’ve spent years evaluating, testing, and writing best practices for technical writers at our companies. Our recommendations go beyond defining elements: We’ll show you how and when to use an element, how to write effective text for that element, and even when not to use specific elements and attributes.

One consistent question that we hear at conferences and community discussions is, “How did you agree on best practices and write those guidelines?” The answer is years and years of trial and error until we refined our guidelines to a set of standards that help us to create industry-leading technical information.

For example, we’ve presented our short description best practices at DITA conferences and user group forums and meetings. At one presentation, a colleague said, “I wish someone would sell us these best practices so we don’t have to spend months writing our own guidelines.” Good idea!

Writers, editors, information architects, and even managers will find helpful guidelines and best practices for writing, organizing, and editing DITA content, and converting nonDITA content to DITA topics:

  • Technical writers will learn how topic-based writing in DITA can help them create more effective information.

  • Editors will learn about new ways to ensure the quality of the information.

  • Information and XML architects will get practical advice about which DITA elements and features to implement.

  • Project managers will find roadmaps and checklists to help them coordinate the conversion to DITA.

  • Technical writing managers will find information about roles and resources required for converting content to DITA.

We created these examples and best practices by using out-of-the-box DITA authoring and processing tools. We used DITA 1.1 in the XMetaL authoring tool and produced PDF and HTML output by using the DITA Open Toolkit. In some cases, we highlighted features that are unique to DITA 1.2. You, too, can create effective topic-based information by using the default settings in DITA.

You can find a number of resources to help you learn DITA basics, and the DITA community is a wonderfully supportive group.

In some chapters, we refer to two other books that cover similar topics: The IBM Style Guide: Conventions for Writers and Editors by DeRespinis et al. (ISBN: 9780132101301), and Developing Quality Technical Information: A Handbook for Writers and Editors by Hargis et al. (ISBN: 9780137034574), both published by IBM Press (Pearson Education, Inc.).

We hope that you find these guidelines helpful. Now, let’s have some fun with DITA!

eBook Bundle Version

Direct from industry experts in information development comes an eBook bundle that combines three titles for technical writers, editors, and information architects: Best Practices for Technical Writers and Editors: DITA, Quality, and Style (Collection) by IBM Press. This set of titles is the most comprehensive collection of resources available for technical communicators.

DITA Best Practices covers Darwin Information Typing Architecture (DITA)—today’s most powerful toolbox for constructing topic-based information. The IBM Style Guide provides complete, proven guidelines for writing consistent, clear, concise, and easy-to-translate content. Developing Quality Technical Information is the definitive guide to developing outstanding technical documentation—for the web and for print.


You are currently reading a PREVIEW of this book.


Get instant access to over $1 million worth of books and videos.


Start a Free 10-Day Trial

  • Safari Books Online
  • Create BookmarkCreate Bookmark
  • Create Note or TagCreate Note or Tag
  • PrintPrint