SPECIAL OFFER
Use code BACKTOLEARN during checkout to save 50% on books, eBooks, & videos. Shop now.
Register your product to gain access to bonus material or receive a coupon.
This EPUB will be accessible from your Account page after purchase.
This eBook requires no passwords or activation to read. We customize your eBook by discreetly watermarking it with your name, making it uniquely yours.
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:
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:
Acknowledgments
About the Authors
Video Demonstrations
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
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: <ol>, <ul>, <sl>, and <dl>
Including Graphics: <fig>, <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: <ul> and <dl>
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
PART II: ARCHITECTING CONTENT
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
Bookmaps
Submaps
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
PART III: CONVERTING AND EDITING
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