Always Learning

Advanced Search

DITA Best Practices

DITA Best Practices

A Roadmap for Writing, Editing, and Architecting in DITA

Laura Bellamy, Michelle Carey, Jenifer Schlotfeldt

Oct 2011, Paperback, 288 pages
ISBN13: 9780132480529
ISBN10: 0132480522
  • Print pagePrint page
  • Email this pageEmail page
  • Write a reviewWrite a review
  • Share

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

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

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

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

Acknowledgments xviii

About the Authors xx

Introduction 1

PART I: WRITING IN DITA 5

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: <title> 24

Introducing the Task: <shortdesc> 25

Adding More Background Information: <context> 25

Describing Prerequisites: <prereq> 26

Writing the Procedure: <steps> and <steps-unordered> 28

Concluding the Task: <example>, <postreq>, and <result> 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: <title> 43

Introducing the Concept Topic: <shortdesc> 44

Writing the Concept: <conbody> 44

Organizing the Concept: <section> 44

Adding Lists: <ol>, <ul>, <sl>, and <dl> 45

Including Graphics: <fig>, <title>, and <image> 48

Highlighting New Terms: <term> 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: <title> 53

Introducing the Reference Information: <shortdesc> 54

Organizing the Reference Information: <section> 54

Creating Tables: <table>, <simpletable>, and <properties> 56

Adding Lists: <ul> and <dl> 58

Creating Syntax Diagrams: <refsyn> and <syntaxdiagram> 59

To Wrap Up 60

Chapter 5 Short Descriptions 63

The <shortdesc> 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 <abstract> 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

PART II: ARCHITECTING CONTENT 89

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

PART III: CONVERTING AND EDITING 201

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 <required-cleanup> 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


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.

Your opinions count

Be the first to review this product. Write your review now.