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

Description

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

Sample Content

Table of Contents

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    
 

Updates

Submit Errata