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


This is the video enhanced eBook version of the print title. Watch video demonstrations to see how to implement some of the advanced features of DITA discussed in this book. With these videos you’ll learn to code short descriptions, links, conditional processing, and content references.  In addition, you will find instructions in the last few pages of your eBook that direct you to the download site for the set of DITA sample files used in examples throughout the book.

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

Available on NOOK devices and apps  
  • NOOK Devices
  • Samsung Galaxy Tab 4 NOOK 7.0
  • Samsung Galaxy Tab 4 NOOK 10.1
  • NOOK HD Tablet
  • NOOK HD+ Tablet
  • NOOK Color
  • NOOK Tablet
  • Tablet/Phone
  • NOOK for Android

Want a NOOK? Explore Now

NOOK Book (eBook)
BN.com price
(Save 12%)$42.99 List Price


This is the video enhanced eBook version of the print title. Watch video demonstrations to see how to implement some of the advanced features of DITA discussed in this book. With these videos you’ll learn to code short descriptions, links, conditional processing, and content references.  In addition, you will find instructions in the last few pages of your eBook that direct you to the download site for the set of DITA sample files used in examples throughout the book.


The Start-to-Finish, Best-Practice Guide to Implementing and Using DITA


Darwin Information Typing Architecture (DITA) is today’s most powerful toolbox for constructing information. By implementing DITA, organizations can gain more value from their technical documentation than ever before. Now, three DITA pioneers offer the first complete roadmap for successful DITA adoption, implementation, and usage.


Drawing on years of experience helping large organizations adopt DITA, the authors answer crucial questions the “official” DITA documents ignore, including: Where do you start? What should you know up front? What are the pitfalls in implementing DITA? How can you avoid those pitfalls?


The authors begin with topic-based writing, presenting proven best practices for developing effective topics and short descriptions. Next, they address content architecture, including how best to set up and implement DITA maps, linking strategies, metadata, conditional processing, and content reuse. Finally, they offer “in the trenches” solutions for ensuring quality implementations, including guidance on content conversion.


Coverage includes:  

  • Knowing how and when to use each DITA element–and when not to
  • Writing “minimalist,” task-oriented information that quickly meets users’ needs
  • Creating effective task, concept, and reference topics for any product, technology, or service
  • Writing effective short descriptions that work well in all contexts
  • Structuring DITA maps to bind topics together and provide superior navigation
  • Using links to create information webs that improve retrievability and navigation
  • Gaining benefits from metadata without getting lost in complexity
  • Using conditional processing to eliminate redundancy and rework
  • Systematically promoting reuse to improve quality and reduce costs
  • Planning, resourcing, and executing effective content conversion
  • Improving quality by editing DITA content and XML markup 

If you’re a writer, editor, information architect, manager, or consultant who evaluates, deploys, or uses DITA, this book will guide you all the way to success.


Important note: The audio and video content included with this enhanced eBook can be viewed only using iBooks on an iPad, iPhone, or iPod touch.


Due to the incredibly rich media included in your enhanced eBook, you may experience longer than usual download times. Please be patient while your product is delivered.


Also see the other books in this IBM Press series:

  • Developing Quality Technical Information: A Handbook for Writers and Editors
  • The IBM Style Guide: Conventions for Writers and Editors
Read More Show Less

Product Details

  • ISBN-13: 9780132929646
  • Publisher: Pearson Education
  • Publication date: 1/3/2012
  • Sold by: Barnes & Noble
  • Format: eBook
  • Edition number: 1
  • Pages: 266
  • File size: 391 MB
  • Note: This product may take a few minutes to download.

Meet the Author

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.

Read More Show Less

Table of Contents

About the Authors

Video Demonstrations


Chapter 1 Topic-Based Writing in DITA
Books, Topics, and Webs of Information
Advantages of Writing in Topics for Writing Teams
Writers Can Work More Productively
Writers Can Share Content with Other Writers
Writers Can Reuse Topics
Writers Can More Quickly Organize or Reorganize Content
Reviewers Can Review Small Groups of Topics Instead of Long Books
DITA Topic Types
Task Orientation
Task Analysis
Minimalist Writing
Know Your Audience
Remove Nonessential Content
Focus on User Goals, Not Product Functions
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
Task Topic Checklist

Chapter 3 Concept Topics
Concept Components and DITA Elements
Titling the Concept Topic: <title>
Introducing the Concept Topic: <shortdesc>
Writing the Concept: <conbody>
Organizing the Concept: <section>
Adding Lists: and
Including Graphics: , <title>, and <image>
Highlighting New Terms: <term>
To Wrap Up

Chapter 4 Reference Topics
Describe One Type of Reference Material per Topic
Organize Reference Information Effectively
Format Reference Information Consistently
Reference Components and DITA Elements
Titling the Reference topic: <title>
Introducing the Reference Information: <shortdesc>
Organizing the Reference Information: <section>
Creating Tables: <table>, <simpletable>, and <properties>
Adding Lists: and
Creating Syntax Diagrams: <refsyn> and <syntaxdiagram>
To Wrap Up

Chapter 5 Short Descriptions
The <shortdesc> Element
How the Short Description Is Used
Guidelines for Writing Effective Short Descriptions
Briefly State the Purpose of the Topic
Include a Short Description in Every Topic
Use Complete, Grammatical Sentences
Don’t Introduce Lists, Figures, or Tables
Keep Short Descriptions Short
Short Descriptions for Task, Concept, and Reference Topics
Task Topic Short Descriptions
Reference Topic Short Descriptions
Writing Short Descriptions for Converted Content
The <abstract> Element
Using More DITA Elements in the Topic Introduction
Including Multiple Short Descriptions
To Wrap Up
Short Description Examples


Chapter 6 DITA Maps and Navigation
DITA Map Structure
Include Topics in a DITA Map
Define Relationships Between Topics
Information Organization
Information Modeling
Benefits of Information Modeling
Building Information Models
DITA Map Ownership
Structure Content in a DITA Map
Group Topics Regardless of Hierarchy
Reference Non-DITA Content
Include Relationship Tables in DITA Maps
Override Topic Titles and Short Descriptions
Navigation Titles
Short Descriptions
Suppressing Topics from the Table of Contents
Suppressing Content from PDF Output
Suppressing Content from HTML Output
To Wrap Up
Navigation and DITA Maps Checklist

Chapter 7 Linking
Hierarchical Links
Inline Links
Link to Prerequisite and Postrequisite Information
Avoid Inline Links to Tables and Figures in a Topic
Create Inline Links to Repeated Steps
Create Inline Links to High-Level Tasks
Control How Links Are Displayed
Related Links
Relationship Tables
Related Link Element
Collection Types
Sequence Collection Type
Choice Collection Type
Family Collection Type
Determining Which Collection Type to Use
Collection Types in Relationship Tables
Links Created with the Importance Attribute
Linking Scope
Local Links
External Links
Peer Links
Link Testing
To Wrap Up
Linking Checklist

Chapter 8 Metadata
Why Is Metadata Important
Types of Metadata
Index Entries
Conditional Processing Attributes
Importance, Status, and Translate Metadata Attributes
Topic Metadata
DITA Map Metadata
Custom Metadata
Metadata Inheritance
To Wrap Up
Metadata Checklist

Chapter 9 Conditional Processing
Conditional Processing Attributes
Creating a Conditional Processing Scheme
Example of a Conditional Processing Scheme
Applying Conditional Processing Attributes
Excluding and Including Content
Flagging Content
Improving Retrievability by Applying Metadata to Topics and DITA Maps
Multiple and Compound Conditions
Multiple Conditions
Compound Conditions
Processing Logic for Multiple and Compound Conditions
Identifying Applied Conditional Values
Testing Your Scheme
To Wrap Up
Conditional Processing Checklist

Chapter 10 Content Reuse
Benefits of Reuse
Ways to Reuse Content
Reusing Elements by Using Content References
Reusing Topics
Reusing DITA Maps
Reusing Content from Non-DITA Sources
Writing for Reuse
Deciding Which Content to Reuse
Step 1: Analyze Your Content
Step 2: Identify Duplicate and Near Duplicate Content
Step 3: Address the Duplication
Step 4: Reorganize and Rewrite for Reuse
Step 5: Implement the Reuse Strategy
Track Your Reuse
To Wrap Up
Reuse Checklist


Chapter 11 Converting Content to DITA
Conversion Goals
Create a Pilot Team
Conversion Process
Step 1. Assess the State of Your Content
Content Analysis Worksheet
Step 2. Plan the Conversion
Scheduling the Conversion
Converting the Content In-House or Hiring a Vendor
Staffing Your Conversion Team
Deciding on a Conversion Strategy
Defining your XML Standard
Establishing Graphics Formats
Establishing DITA File Requirements
Deciding What DITA Topic Types You Need
Establishing an Architecture for Your DITA Maps
Handling Special Structures in Your Source Files
Step 3. Prepare the Content for Conversion
Conversion Workshops
Step 4. Convert Your Source Files
Step 5. Address Postconversion Issues
Phase 1: Address <required-cleanup> Elements
Phase 2: Fix Maps and Linking
Phase 3: Improve Topics
Phase 4: Check for Markup Problems and Do Code Reviews
Phase 5: Exploit DITA
Step 6. Evaluate the Conversion Process
To Wrap Up
Conversion Sizing Table

Chapter 12 DITA Code Editing
Code Reviews
Code Review Benefits
Identifying Code Reviewers
Limiting the Scope of the Review
Preparing for Code Reviews
Using Special Style Sheets for Revealing Problems in the Markup
Performing a Code Review
Step 1: Schedule the Code Review
Step 2: Submit the DITA Topics for Review
Step 3: Review the DITA Markup
Step 4: Discuss Review Findings
Step 5: Complete the Code Review
Code Reviews for Content Not in Topic Form
To Wrap Up
Code Review Checklist

Chapter 13 Content Editing
Defining, Scheduling, and Submitting Content Edits
Defining the Types of Content Edits
Scheduling the Edits
Submitting Content for Editing
Providing Editorial Feedback
Inserting Draft Comments
Inserting XML Comments
Tracking Changes
Comparing Original and Edited Files
Editing the Content in DITA Topics and Maps
Editing DITA Topics
Editing the Output
To Wrap Up
Content Editing Checklist
Read More Show Less

Customer Reviews

Be the first to write a review
( 0 )
Rating Distribution

5 Star


4 Star


3 Star


2 Star


1 Star


Your Rating:

Your Name: Create a Pen Name or

Barnes & Noble.com Review Rules

Our reader reviews allow you to share your comments on titles you liked, or didn't, with others. By submitting an online review, you are representing to Barnes & Noble.com that all information contained in your review is original and accurate in all respects, and that the submission of such content by you and the posting of such content by Barnes & Noble.com does not and will not violate the rights of any third party. Please follow the rules below to help ensure that your review can be posted.

Reviews by Our Customers Under the Age of 13

We highly value and respect everyone's opinion concerning the titles we offer. However, we cannot allow persons under the age of 13 to have accounts at BN.com or to post customer reviews. Please see our Terms of Use for more details.

What to exclude from your review:

Please do not write about reviews, commentary, or information posted on the product page. If you see any errors in the information on the product page, please send us an email.

Reviews should not contain any of the following:

  • - HTML tags, profanity, obscenities, vulgarities, or comments that defame anyone
  • - Time-sensitive information such as tour dates, signings, lectures, etc.
  • - Single-word reviews. Other people will read your review to discover why you liked or didn't like the title. Be descriptive.
  • - Comments focusing on the author or that may ruin the ending for others
  • - Phone numbers, addresses, URLs
  • - Pricing and availability information or alternative ordering information
  • - Advertisements or commercial solicitation


  • - By submitting a review, you grant to Barnes & Noble.com and its sublicensees the royalty-free, perpetual, irrevocable right and license to use the review in accordance with the Barnes & Noble.com Terms of Use.
  • - Barnes & Noble.com reserves the right not to post any review -- particularly those that do not follow the terms and conditions of these Rules. Barnes & Noble.com also reserves the right to remove any review at any time without notice.
  • - See Terms of Use for other conditions and disclaimers.
Search for Products You'd Like to Recommend

Recommend other products that relate to your review. Just search for them below and share!

Create a Pen Name

Your Pen Name is your unique identity on BN.com. It will appear on the reviews you write and other website activities. Your Pen Name cannot be edited, changed or deleted once submitted.

Your Pen Name can be any combination of alphanumeric characters (plus - and _), and must be at least two characters long.

Continue Anonymously

    If you find inappropriate content, please report it to Barnes & Noble
    Why is this product inappropriate?
    Comments (optional)