Brain Candy Sale

Special Offers see all

Enter to WIN a $100 Credit

Subscribe to
for a chance to win.
Privacy Policy

Visit our stores

    Recently Viewed clear list

    Contributors | September 15, 2015

    Mary Karr: IMG Memoir Tutorials with Mary Karr, Lena Dunham, and Gary Shteyngart

    Editor's note: It's been 20 years since the groundbreaking memoir The Liars' Club sent Mary Karr into the literary spotlight with its phenomenal... Continue »
    1. $17.49 Sale Hardcover add to wish list

      The Art of Memoir

      Mary Karr 9780062223067


This item may be
out of stock.

Click on the button below to search for this title in other formats.

Check for Availability
Add to Wishlist

This title in other editions

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


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


Synopses & Reviews

Publisher Comments:

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, and how can you avoid them?"

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" toWriting "minimalist," task-oriented information that quickly meets users' needsCreating effective task, concept, and reference topics for any product, technology, or serviceWriting effective short descriptions that work well in all contextsStructuring DITA maps to bind topics together and provide superior navigationUsing links to create information webs that improve retrievability and navigationGaining benefits from metadata without getting lost in complexityUsing conditional processing to eliminate redundancy and reworkSystematically promoting reuse to improve quality and reduce costsPlanning, resourcing, and executing effective content conversionImproving quality by editing DITA content and XML markup

If you're a writer, editor, information architect, manager, or consultant involved with evaluating, deploying, or using DITA, this book will guide you all the way to success.

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"

About 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.

Table of Contents

Normal 0 false false false MicrosoftInternetExplorer4

Acknowledgments xviii

About the Authors xx

Introduction 1


Chapter 1 Topic-Based Writing in DITA 7

Books, Topics, and Webs of Information 7

Advantages of Writing in Topics for Writing Teams 9

Writers Can Work More Productively 9

Writers Can Share Content with Other Writers 9

Writers Can Reuse Topics 10

Writers Can More Quickly Organize or Reorganize Content 10

Reviewers Can Review Small Groups of Topics Instead of Long Books 10

DITA Topic Types 10

Task Orientation 12

Task Analysis 13

Minimalist Writing 16

Know Your Audience 16

Remove Nonessential Content 16

Focus on User Goals, Not Product Functions 16

To Wrap Up 17

Topic-Based Writing Checklist 18

Task analysis form 19

Chapter 2 Task Topics 21

Separate Task Information from Conceptual or Reference Information 22

Write One Procedure per Topic 22

Create Subtasks to Organize Long Procedures 22

Task Components and DITA Elements 23

Titling the Task: 24

Introducing the Task: 25

Adding More Background Information: 25

Describing Prerequisites: 26

Writing the Procedure: and 28

Concluding the Task: , , and 35

Task Topic Checklist 39

Chapter 3 Concept Topics 41

Describe One Concept per Topic 42

Create a Concept Topic Only if the Idea Can’t Be Covered More Concisely Elsewhere 42

Separate Task Information from Conceptual Information 42

Concept Components and DITA Elements 43

Titling the Concept Topic: 43

Introducing the Concept Topic: 44

Writing the Concept: 44

Organizing the Concept: 44

Adding Lists:

      , , and 45

      Including Graphics: , , and 48

      Highlighting New Terms: 48

      To Wrap Up 49

      Concept Topic Checklist 50

      Chapter 4 Reference Topics 51

      Describe One Type of Reference Material per Topic 51

      Organize Reference Information Effectively 52

      Format Reference Information Consistently 52

      Reference Components and DITA Elements 52

      Titling the Reference topic: 53

      Introducing the Reference Information: 54

      Organizing the Reference Information: 54

      Creating Tables: , , and 56

      Adding Lists:

        and 58

        Creating Syntax Diagrams: and 59

        To Wrap Up 60

        Chapter 5 Short Descriptions 63

        The Element 63

        How the Short Description Is Used 63

        Guidelines for Writing Effective Short Descriptions 66

        Briefly State the Purpose of the Topic 67

        Include a Short Description in Every Topic 68

        Use Complete, Grammatical Sentences 69

        Don’t Introduce Lists, Figures, or Tables 70

        Keep Short Descriptions Short 71

        Short Descriptions for Task, Concept, and Reference Topics 75

        Task Topic Short Descriptions 75

        Concept Topic Short Descriptions 79

        Reference Topic Short Descriptions 80

        Writing Short Descriptions for Converted Content 81

        The Element 81

        Using More DITA Elements in the Topic Introduction 82

        Including Multiple Short Descriptions 83

        To Wrap Up 84

        Short Description Examples 85

        Short Description Checklist 87


        Chapter 6 DITA Maps and Navigation 91

        DITA Map Structure 91

        Relationships Between Topics 92

        Information Organization 92

        Information Modeling 96

        Benefits of Information Modeling 96

        Building Information Models 97

        Bookmaps 97

        Submaps 98

        DITA Map Ownership 101

        Include Relationship Tables in DITA Maps 101

        Override Topic Titles and Short Descriptions 102

        Navigation Titles 102

        Short Descriptions 102

        Provide Unique Short Descriptions for Reused Topics 103

        Provide Short Descriptions for Links to Non-DITA Content 105

        Suppressing Topics from the Table of Contents

        Suppressing Content from PDF Output 106

        Suppressing Content from HTML Output 107

        To Wrap Up 107

        Navigation and DITA Maps Checklist 108

        Chapter 7 Linking 109

        Hierarchical Links 109

        Inline Links 111

        Link to Prerequisite and Postrequisite Information 113

        Avoid Inline Links to Tables and Figures in a Topic 114

        Create Inline Links to Repeated Steps 115

        Create Inline Links to High-Level Tasks 115

        Control How Links Are Displayed 116

        Related Links 117

        Relationship Tables 118

        Implementing Relationship Tables 122

        Collection Types 123

        Sequence Collection Type 124

        Choice Collection Type 127

        Unordered Collection Type 128

        Family Collection Type 129

        Determining Which Collection Type to Use 130

        Collection Types in Relationship Tables 131

        Links Created with the Importance Attribute 133

        Linking Scope 134

        Local Links 136

        External Links 136

        Peer Links 137

        Relative Paths for Links 138

        Link Testing 138

        To Wrap Up 138

        Linking Checklist 140

        Chapter 8 Metadata 143

        Why Is Metadata Important 143

        Types of Metadata 144

        Index Entries 145

        Conditional Processing Attributes 149

        Importance, Status, and Translate Metadata Attributes 150

        Topic Metadata 150

        DITA Map Metadata 152

        Custom Metadata 154

        Metadata Inheritance 155

        To Wrap Up 158

        Metadata Checklist 158

        Chapter 9 Conditional Processing 161

        Conditional Processing Attributes 163

        Creating a Conditional Processing Scheme 164

        Example of a Conditional Processing Scheme 164

        Applying Conditional Processing Attributes 166

        Applying Conditions to Content in Topics 166

        Applying Conditions to DITA Maps and Relationship Tables 169

        Excluding and Including Content 171

        Flagging Content 171

        Multiple and Compound Conditions 173

        Multiple Conditions 174

        Compound Conditions 174

        Processing Logic for Multiple and Compound Conditions 174

        Identifying Applied Conditional Values 178

        Testing Your Scheme 179

        Improving Content Retrievability for the Writing Team 179

        To Wrap Up 179

        Conditional Processing Checklist 180

        Chapter 10 Content Reuse 183

        Benefits of Reuse 183

        Ways to Reuse Content 184

        Reusing Elements by Using Content References 184

        Conref Attribute 187

        Phrase-Level Reuse 190

        Designated Source Files for Conrefs 180

        Reusing Topics 192

        Copy-to Attribute 192

        Reusing DITA Maps 194

        Reusing Content from Non-DITA Sources 195

        Writing for Reuse 195

        Deciding Which Content to Reuse 196

        Step 1: Analyze Your Content 197

        Step 2: Identify Duplicate and Near Duplicate Content 197

        Step 3: Address the Duplication 197

        Step 4: Reorganize and Rewrite for Reuse 197

        Step 5: Implement the Reuse Strategy 197

        Track Your Reuse 198

        To Wrap Up 198

        Reuse Checklist 199


        Chapter 11 Converting Content to DITA 203

        Conversion Goals 203

        Create a Pilot Team 204

        Conversion Process 204

        Step 1. Assess the State of Your Content 205

        Content Analysis Worksheet 205

        Step 2. Plan the Conversion 207

        Scheduling the Conversion 207

        Converting the Content In-House 208or Hiring a Vendor 208

        Staffing Your Conversion Team 209

        Deciding on a Conversion Strategy 210

        Defining your XML Standard 212

        Establishing Graphics Formats 212

        Establishing DITA File Requirements 214

        Deciding What DITA Topic Types You Nee217d 217

        Establishing an Architecture for Your DITA Ma218ps 218

        Handling Special Structures in Your Source Files 219

        Step 3. Prepare the Content for Conversion 219

        Conversion Workshops 221

        Step 4. Convert Your Source Files 222

        Step 5. Address Postconversion Issues 222

        Phase 1: Address Elements 222

        Phase 2: Fix Maps and Linking 222

        Phase 3: Improve Topics 223

        Phase 4: Check for Markup Problems and Do Code Reviews 223

        Phase 5: Exploit DITA 224

        Step 6. Evaluate the Conversion Process 224

        To Wrap Up 224

        Conversion Sizing Table 225

        DITA Conversion Checklist 226

        Chapter 12 DITA Code Editing 229

        Code Reviews 230

        Code Review Benefits 230

        Identifying Code Reviewers 232

        Limiting the Scope of the Review 232

        Preparing for Code Reviews 233

        Using Special Style Sheets for Revealing Problems in the Markup 233

        Performing a Code Review 234

        Step 1: Schedule the Code Review 234

        Step 2: Submit the DITA Topics for Review 235

        Step 3: Review the DITA Markup 235

        Common Problems Found in Task Topics 236

        Common Problems Found in Concept Topics 241

        Common Problems Found in Reference Topics 246

        Common Problems Found in All Topic Types 249

        Common Problems Found in DITA Maps 254

        Common Problems Found in Metadata 254

        Step 4: Discuss Review Findings 254

        Step 5: Complete the Code Review 255

        Code Reviews for Content Not in Topic Form 255

        To Wrap Up 256

        Code Review Checklist 257

        Chapter 13 Content Editing 259

        Defining, Scheduling, and Submitting Content Edits 260

        Defining the Types of Content Edits 260

        Scheduling the Edits 261

        Submitting Content for Edi262ting 262

        Providing Editorial Feedback 263

        Inserting Draft Comments 263

        Inserting XML Comments 265

        Tracking Changes 266

        Comparing Original and Edited Files 268

        Editing the Content in DITA Topics and Maps 268

        Editing DITA Topics 268

        Editing DITA Maps 269

        Editing the Output 270

        To Wrap Up 270

        Content Editing Checklist 271

        Index 273

Product Details

IBM Press
Computers : Digital Media - Desktop Publishing
Schlotfeldt, Jenifer
Bellamy, Laura
Carey, Michelle
Adapted by:
Schlotfeldt, Jenifer
Abridged by:
Carey, Michelle
Publication Date:
August 2011

Related Subjects

Computers and Internet » Desktop Publishing » General
Reference » Writing » Writing as a Business

DITA Best Practices: A Roadmap for Writing, Editing, and Architecting in DITA
0 stars - 0 reviews
$ In Stock
Product details 263 pages Pearson Education - English 9780132374323 Reviews:
  • back to top


Powell's City of Books is an independent bookstore in Portland, Oregon, that fills a whole city block with more than a million new, used, and out of print books. Shop those shelves — plus literally millions more books, DVDs, and gifts — here at