DITA Best Practices: A Roadmap for Writing, Editing, and Architecting in DITA by Laura BellamyDITA Best Practices: A Roadmap for Writing, Editing, and Architecting in DITA by Laura Bellamy

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

byLaura Bellamy, Michelle Carey, Jenifer Schlotfeldt

Paperback | September 30, 2011

Pricing and Purchase Info


Earn 250 plum® points

Prices and offers may vary in store

Out of stock online

Not available in stores


&>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
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...
Title:DITA Best Practices: A Roadmap for Writing, Editing, and Architecting in DITAFormat:PaperbackDimensions:288 pages, 9 × 6.9 × 0.8 inPublished:September 30, 2011Publisher:Pearson EducationLanguage:English

The following ISBNs are associated with this title:

ISBN - 10:0132480522

ISBN - 13:9780132480529

Look for similar items by category:


Table of Contents

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<p /> <p style="margin%3a0px%3b" />    Introducing the Task: <shortdesc>     25<p /> <p style="margin%3a0px%3b" />    Adding More Background Information: <context>     25<p /> <p style="margin%3a0px%3b" />    Describing Prerequisites: <prereq>     26<p /> <p style="margin%3a0px%3b" />    Writing the Procedure: <steps> and <steps-unordered>     28<p /> <p style="margin%3a0px%3b" />    Concluding the Task: <example>, <postreq>, and <result>     35<p /> <p style="margin%3a0px%3b">Task Topic Checklist     39</p> <p style="margin%3a0px%3b"> </p> <p style="margin%3a0px%3b"> <strong>Chapter 3  Concept Topics     41</strong> </p> <p style="margin%3a0px%3b">Describe One Concept per Topic     42</p> <p style="margin%3a0px%3b">Create a Concept Topic Only if the Idea Can’t Be Covered More Concisely Elsewhere     42</p> <p style="margin%3a0px%3b">Separate Task Information from Conceptual Information     42</p> <p style="margin%3a0px%3b">Concept Components and DITA Elements     43</p> <p style="margin%3a0px%3b" />    Titling the Concept Topic: <title>     43<p /> <p style="margin%3a0px%3b" />    Introducing the Concept Topic: <shortdesc>     44<p /> <p style="margin%3a0px%3b" />    Writing the Concept: <conbody>     44<p /> <p style="margin%3a0px%3b" />    Organizing the Concept: <section>     44<p /> <p style="margin%3a0px%3b" />    Adding Lists: <ol>, <ul>, <sl>, and <dl>     45<p /> <p style="margin%3a0px%3b" />    Including Graphics: <fig>, <title>, and <image>     48<p /> <p style="margin%3a0px%3b" />    Highlighting New Terms: <term>     48<p /> <p style="margin%3a0px%3b">To Wrap Up     49</p> <p style="margin%3a0px%3b">Concept Topic Checklist     50</p> <p style="margin%3a0px%3b"> </p> <p style="margin%3a0px%3b"> <strong>Chapter 4  Reference Topics     51</strong> </p> <p style="margin%3a0px%3b">Describe One Type of Reference Material per Topic     51</p> <p style="margin%3a0px%3b">Organize Reference Information Effectively     52</p> <p style="margin%3a0px%3b">Format Reference Information Consistently     52</p> <p style="margin%3a0px%3b">Reference Components and DITA Elements     52</p> <p style="margin%3a0px%3b" />    Titling the Reference topic: <title>     53<p /> <p style="margin%3a0px%3b" />    Introducing the Reference Information: <shortdesc>     54<p /> <p style="margin%3a0px%3b" />    Organizing the Reference Information: <section>     54<p /> <p style="margin%3a0px%3b" />    Creating Tables: <table>, <simpletable>, and <properties>     56<p /> <p style="margin%3a0px%3b" />    Adding Lists: <ul> and <dl>     58<p /> <p style="margin%3a0px%3b" />    Creating Syntax Diagrams: <refsyn> and <syntaxdiagram>     59<p /> <p style="margin%3a0px%3b">To Wrap Up     60</p> <p style="margin%3a0px%3b"> </p> <p style="margin%3a0px%3b"> <strong>Chapter 5  Short Descriptions     63</strong> </p> <p style="margin%3a0px%3b" />The <shortdesc> Element     63<p /> <p style="margin%3a0px%3b">    How the Short Description Is Used     63</p> <p style="margin%3a0px%3b">Guidelines for Writing Effective Short Descriptions     66</p> <p style="margin%3a0px%3b">    Briefly State the Purpose of the Topic     67</p> <p style="margin%3a0px%3b">    Include a Short Description in Every Topic     68</p> <p style="margin%3a0px%3b">    Use Complete, Grammatical Sentences     69</p> <p style="margin%3a0px%3b">    Don’t Introduce Lists, Figures, or Tables     70</p> <p style="margin%3a0px%3b">    Keep Short Descriptions Short     71</p> <p style="margin%3a0px%3b">Short Descriptions for Task, Concept, and Reference Topics     75</p> <p style="margin%3a0px%3b">    Task Topic Short Descriptions     75</p> <p style="margin%3a0px%3b">    Concept Topic Short Descriptions     79</p> <p style="margin%3a0px%3b">    Reference Topic Short Descriptions     80</p> <p style="margin%3a0px%3b">Writing Short Descriptions for Converted Content     81</p> <p style="margin%3a0px%3b" />The <abstract> Element     81<p /> <p style="margin%3a0px%3b">    Using More DITA Elements in the Topic Introduction     82</p> <p style="margin%3a0px%3b">    Including Multiple Short Descriptions     83</p> <p style="margin%3a0px%3b">To Wrap Up     84</p> <p style="margin%3a0px%3b">Short Description Examples     85</p> <p style="margin%3a0px%3b">Short Description Checklist     87</p> <p style="margin%3a0px%3b"> </p> <p style="margin%3a0px%3b"> <strong>PART II:  ARCHITECTING CONTENT     89</strong> </p> <p style="margin%3a0px%3b"> </p> <p style="margin%3a0px%3b"> <strong>Chapter 6  DITA Maps and Navigation     91</strong> </p> <p style="margin%3a0px%3b">DITA Map Structure     91</p> <p style="margin%3a0px%3b">    Relationships Between Topics     92</p> <p style="margin%3a0px%3b">Information Organization     92</p> <p style="margin%3a0px%3b">Information Modeling     96</p> <p style="margin%3a0px%3b">    Benefits of Information Modeling     96</p> <p style="margin%3a0px%3b">    Building Information Models     97</p> <p style="margin%3a0px%3b">Bookmaps     97</p> <p style="margin%3a0px%3b">Submaps     98</p> <p style="margin%3a0px%3b">DITA Map Ownership     101</p> <p style="margin%3a0px%3b">Include Relationship Tables in DITA Maps     101</p> <p style="margin%3a0px%3b">Override Topic Titles and Short Descriptions     102</p> <p style="margin%3a0px%3b">    Navigation Titles     102</p> <p style="margin%3a0px%3b">Short Descriptions     102</p> <p style="margin%3a0px%3b">    Provide Unique Short Descriptions for Reused Topics     103</p> <p style="margin%3a0px%3b">    Provide Short Descriptions for Links to Non-DITA Content     105</p> <p style="margin%3a0px%3b">Suppressing Topics from the Table of Contents     </p> <p style="margin%3a0px%3b">Suppressing Content from PDF Output     106</p> <p style="margin%3a0px%3b">Suppressing Content from HTML Output     107</p> <p style="margin%3a0px%3b">To Wrap Up     107</p> <p style="margin%3a0px%3b">Navigation and DITA Maps Checklist     108</p> <p style="margin%3a0px%3b"> </p> <p style="margin%3a0px%3b"> <strong>Chapter 7  Linking     109</strong> </p> <p style="margin%3a0px%3b">Hierarchical Links     109</p> <p style="margin%3a0px%3b">Inline Links     111</p> <p style="margin%3a0px%3b">    Link to Prerequisite and Postrequisite Information     113</p> <p style="margin%3a0px%3b">    Avoid Inline Links to Tables and Figures in a Topic     114</p> <p style="margin%3a0px%3b">    Create Inline Links to Repeated Steps     115</p> <p style="margin%3a0px%3b">    Create Inline Links to High-Level Tasks     115</p> <p style="margin%3a0px%3b">Control How Links Are Displayed     116</p> <p style="margin%3a0px%3b">Related Links     117</p> <p style="margin%3a0px%3b">    Relationship Tables     118</p> <p style="margin%3a0px%3b">    Implementing Relationship Tables     122</p> <p style="margin%3a0px%3b">Collection Types     123</p> <p style="margin%3a0px%3b">    Sequence Collection Type     124</p> <p style="margin%3a0px%3b">    Choice Collection Type     127</p> <p style="margin%3a0px%3b">    Unordered Collection Type     128</p> <p style="margin%3a0px%3b">    Family Collection Type     129</p> <p style="margin%3a0px%3b">    Determining Which Collection Type to Use     130</p> <p style="margin%3a0px%3b">    Collection Types in Relationship Tables     131</p> <p style="margin%3a0px%3b">Links Created with the Importance Attribute     133</p> <p style="margin%3a0px%3b">Linking Scope     134</p> <p style="margin%3a0px%3b">    Local Links     136</p> <p style="margin%3a0px%3b">    External Links     136</p> <p style="margin%3a0px%3b">    Peer Links     137</p> <p style="margin%3a0px%3b">Relative Paths for Links     138</p> <p style="margin%3a0px%3b">Link Testing     138</p> <p style="margin%3a0px%3b">To Wrap Up     138</p> <p style="margin%3a0px%3b">Linking Checklist     140</p> <p style="margin%3a0px%3b"> </p> <p style="margin%3a0px%3b"> <strong>Chapter 8  Metadata    143 </strong> </p> <p style="margin%3a0px%3b">Why Is Metadata Important     143</p> <p style="margin%3a0px%3b">Types of Metadata     144</p> <p style="margin%3a0px%3b">    Index Entries     145</p> <p style="margin%3a0px%3b">    Conditional Processing Attributes     149</p> <p style="margin%3a0px%3b">    Importance, Status, and Translate Metadata Attributes     150</p> <p style="margin%3a0px%3b">    Topic Metadata     150</p> <p style="margin%3a0px%3b">    DITA Map Metadata     152</p> <p style="margin%3a0px%3b">Custom Metadata     154</p> <p style="margin%3a0px%3b">Metadata Inheritance     155</p> <p style="margin%3a0px%3b">To Wrap Up     158</p> <p style="margin%3a0px%3b">Metadata Checklist     158</p> <p style="margin%3a0px%3b"> </p> <p style="margin%3a0px%3b"> <strong>Chapter 9  Conditional Processing     161</strong> </p> <p style="margin%3a0px%3b">Conditional Processing Attributes     163</p> <p style="margin%3a0px%3b">Creating a Conditional Processing Scheme     164</p> <p style="margin%3a0px%3b">    Example of a Conditional Processing Scheme     164</p> <p style="margin%3a0px%3b">Applying Conditional Processing Attributes     166</p> <p style="margin%3a0px%3b">    Applying Conditions to Content in Topics     166</p> <p style="margin%3a0px%3b">    Applying Conditions to DITA Maps and Relationship Tables     169</p> <p style="margin%3a0px%3b">    Excluding and Including Content     171</p> <p style="margin%3a0px%3b">    Flagging Content     171</p> <p style="margin%3a0px%3b">Multiple and Compound Conditions     173</p> <p style="margin%3a0px%3b">    Multiple Conditions     174</p> <p style="margin%3a0px%3b">    Compound Conditions     174</p> <p style="margin%3a0px%3b">    Processing Logic for Multiple and Compound Conditions     174</p> <p style="margin%3a0px%3b">Identifying Applied Conditional Values     178</p> <p style="margin%3a0px%3b">Testing Your Scheme     179</p> <p style="margin%3a0px%3b">Improving Content Retrievability for the Writing Team     179</p> <p style="margin%3a0px%3b">To Wrap Up     179</p> <p style="margin%3a0px%3b">Conditional Processing Checklist     180</p> <p style="margin%3a0px%3b"> </p> <p style="margin%3a0px%3b"> <strong>Chapter 10  Content Reuse     183</strong> </p> <p style="margin%3a0px%3b">Benefits of Reuse     183</p> <p style="margin%3a0px%3b">Ways to Reuse Content  184   </p> <p style="margin%3a0px%3b">Reusing Elements by Using Content References     184</p> <p style="margin%3a0px%3b">    Conref Attribute     187</p> <p style="margin%3a0px%3b">    Phrase-Level Reuse     190</p> <p style="margin%3a0px%3b">    Designated Source Files for Conrefs     180</p> <p style="margin%3a0px%3b">Reusing Topics     192</p> <p style="margin%3a0px%3b">    Copy-to Attribute     192</p> <p style="margin%3a0px%3b">Reusing DITA Maps     194</p> <p style="margin%3a0px%3b">Reusing Content from Non-DITA Sources     195</p> <p style="margin%3a0px%3b">Writing for Reuse     195</p> <p style="margin%3a0px%3b">Deciding Which Content to Reuse     196</p> <p style="margin%3a0px%3b">    Step 1: Analyze Your Content     197</p> <p style="margin%3a0px%3b">    Step 2: Identify Duplicate and Near Duplicate Content     197</p> <p style="margin%3a0px%3b">    Step 3: Address the Duplication     197</p> <p style="margin%3a0px%3b">    Step 4: Reorganize and Rewrite for Reuse     197</p> <p style="margin%3a0px%3b">    Step 5: Implement the Reuse Strategy     197</p> <p style="margin%3a0px%3b">Track Your Reuse     198</p> <p style="margin%3a0px%3b">To Wrap Up     198</p> <p style="margin%3a0px%3b">Reuse Checklist     199</p> <p style="margin%3a0px%3b"> </p> <p style="margin%3a0px%3b"> <strong>PART III:  CONVERTING AND EDITING     201</strong> </p> <p style="margin%3a0px%3b"> </p> <p style="margin%3a0px%3b"> <strong>Chapter 11  Converting Content to DITA     203</strong> </p> <p style="margin%3a0px%3b">Conversion Goals     203</p> <p style="margin%3a0px%3b">Create a Pilot Team     204</p> <p style="margin%3a0px%3b">Conversion Process     204</p> <p style="margin%3a0px%3b">Step 1. Assess the State of Your Content     205</p> <p style="margin%3a0px%3b">    Content Analysis Worksheet     205</p> <p style="margin%3a0px%3b">Step 2. Plan the Conversion     207</p> <p style="margin%3a0px%3b">    Scheduling the Conversion     207</p> <p style="margin%3a0px%3b">    Converting the Content In-House 208or Hiring a Vendor     208</p> <p style="margin%3a0px%3b">    Staffing Your Conversion Team     209</p> <p style="margin%3a0px%3b">    Deciding on a Conversion Strategy     210</p> <p style="margin%3a0px%3b">    Defining your XML Standard     212</p> <p style="margin%3a0px%3b">    Establishing Graphics Formats     212</p> <p style="margin%3a0px%3b">    Establishing DITA File Requirements     214</p> <p style="margin%3a0px%3b">    Deciding What DITA Topic Types You Nee217d     217</p> <p style="margin%3a0px%3b">    Establishing an Architecture for Your DITA Ma218ps     218</p> <p style="margin%3a0px%3b">    Handling Special Structures in Your Source Files    219 </p> <p style="margin%3a0px%3b">Step 3. Prepare the Content for Conversion     219</p> <p style="margin%3a0px%3b">    Conversion Workshops     221</p> <p style="margin%3a0px%3b">Step 4. Convert Your Source Files     222</p> <p style="margin%3a0px%3b">Step 5. Address Postconversion Issues     222</p> <p style="margin%3a0px%3b" />    Phase 1: Address <required-cleanup> Elements     222<p /> <p style="margin%3a0px%3b">    Phase 2: Fix Maps and Linking     222</p> <p style="margin%3a0px%3b">    Phase 3: Improve Topics     223</p> <p style="margin%3a0px%3b">    Phase 4: Check for Markup Problems and Do Code Reviews     223</p> <p style="margin%3a0px%3b">    Phase 5: Exploit DITA     224</p> <p style="margin%3a0px%3b">Step 6. Evaluate the Conversion Process     224</p> <p style="margin%3a0px%3b">To Wrap Up     224</p> <p style="margin%3a0px%3b">Conversion Sizing Table     225</p> <p style="margin%3a0px%3b">DITA Conversion Checklist     226</p> <p style="margin%3a0px%3b"> </p> <p style="margin%3a0px%3b"> <strong>Chapter 12  DITA Code Editing     229</strong> </p> <p style="margin%3a0px%3b">Code Reviews     230</p> <p style="margin%3a0px%3b">    Code Review Benefits     230</p> <p style="margin%3a0px%3b">Identifying Code Reviewers     232</p> <p style="margin%3a0px%3b">Limiting the Scope of the Review     232</p> <p style="margin%3a0px%3b">Preparing for Code Reviews     233</p> <p style="margin%3a0px%3b">    Using Special Style Sheets for Revealing Problems in the Markup     233</p> <p style="margin%3a0px%3b">Performing a Code Review     234</p> <p style="margin%3a0px%3b">    Step 1: Schedule the Code Review     234</p> <p style="margin%3a0px%3b">    Step 2: Submit the DITA Topics for Review     235</p> <p style="margin%3a0px%3b">    Step 3: Review the DITA Markup     235</p> <p style="margin%3a0px%3b">    Common Problems Found in Task Topics     236</p> <p style="margin%3a0px%3b">    Common Problems Found in Concept Topics     241</p> <p style="margin%3a0px%3b">    Common Problems Found in Reference Topics     246</p> <p style="margin%3a0px%3b">    Common Problems Found in All Topic Types     249</p> <p style="margin%3a0px%3b">    Common Problems Found in DITA Maps     254</p> <p style="margin%3a0px%3b">    Common Problems Found in Metadata     254</p> <p style="margin%3a0px%3b">    Step 4: Discuss Review Findings     254</p> <p style="margin%3a0px%3b">    Step 5: Complete the Code Review     255</p> <p style="margin%3a0px%3b">Code Reviews for Content Not in Topic Form     255</p> <p style="margin%3a0px%3b">To Wrap Up     256</p> <p style="margin%3a0px%3b">Code Review Checklist     257</p> <p style="margin%3a0px%3b"> </p> <p style="margin%3a0px%3b"> <strong>Chapter 13  Content Editing     259</strong> </p> <p style="margin%3a0px%3b">Defining, Scheduling, and Submitting Content Edits     260</p> <p style="margin%3a0px%3b">    Defining the Types of Content Edits     260</p> <p style="margin%3a0px%3b">    Scheduling the Edits     261</p> <p style="margin%3a0px%3b">    Submitting Content for Edi262ting     262</p> <p style="margin%3a0px%3b">Providing Editorial Feedback     263</p> <p style="margin%3a0px%3b">    Inserting Draft Comments     263</p> <p style="margin%3a0px%3b">    Inserting XML Comments     265</p> <p style="margin%3a0px%3b">    Tracking Changes     266</p> <p style="margin%3a0px%3b">    Comparing Original and Edited Files     268</p> <p style="margin%3a0px%3b">Editing the Content in DITA Topics and Maps     268</p> <p style="margin%3a0px%3b">    Editing DITA Topics     268</p> <p style="margin%3a0px%3b">    Editing DITA Maps     269</p> <p style="margin%3a0px%3b">Editing the Output     270</p> <p style="margin%3a0px%3b">To Wrap Up     270</p> <p style="margin%3a0px%3b">Content Editing Checklist     271</p> <p style="margin%3a0px%3b"> </p> <p style="margin%3a0px%3b"> <strong>Index     273</strong> </p> <p style="margin%3a0px%3b"> <strong> </strong> </p> <p style="margin%3a0px%3b"> </p> </required-cleanup></abstract></shortdesc></syntaxdiagram></refsyn></dl></ul></properties></simpletable></table></section></shortdesc>