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

Description

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

CONTENTS:

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>,

, <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:
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