DITA Best Practices
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
More details
Other editions
Additional editions
Persons
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.
Content
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:
Introducing the Task:
Adding More Background Information:
Describing Prerequisites:
Writing the Procedure:
Concluding the Task:
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:
Introducing the Concept Topic:
Writing the Concept:
Organizing the Concept:
Adding Lists:
Including Graphics:
Highlighting New Terms:
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:
Introducing the Reference Information:
Organizing the Reference Information:
Creating Tables: ,
Adding Lists:
Creating Syntax Diagrams:
To Wrap Up 60
Chapter 5 Short Descriptions 63
The
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
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
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
