Klienditugi: 7440010 (E-R 10-18)

Abi | Registreeri | Logi sisse

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

3.86/5 (114 hinnangut Goodreads-ist)

Laura Bellamy, Michelle Carey, Jenifer Schlotfeldt

Formaat: 304 pages
Sari: IBM Press
Ilmumisaeg: 14-Sep-2011
Kirjastus: IBM Press
Keel: eng
ISBN-13: 9780132479806

Teised raamatud teemal:

Formaat - PDF+DRM
Hind: 27,78 €*
* hind on lõplik, st. muud allahindlused enam ei rakendu
Lisa ostukorvi
Lisa soovinimekirja
See e-raamat on mõeldud ainult isiklikuks kasutamiseks. E-raamatuid ei saa tagastada.

Formaat: 304 pages
Sari: IBM Press
Ilmumisaeg: 14-Sep-2011
Kirjastus: IBM Press
Keel: eng
ISBN-13: 9780132479806

Teised raamatud teemal:

DRM piirangud

Kopeerimine (copy/paste):

ei ole lubatud
Printimine:

ei ole lubatud
Kasutamine:

Digitaalõiguste kaitse (DRM)
Kirjastus on väljastanud selle e-raamatu krüpteeritud kujul, mis tähendab, et selle lugemiseks peate installeerima spetsiaalse tarkvara. Samuti peate looma endale Adobe ID Rohkem infot siin. E-raamatut saab lugeda 1 kasutaja ning alla laadida kuni 6'de seadmesse (kõik autoriseeritud sama Adobe ID-ga).

Vajalik tarkvara
Mobiilsetes seadmetes (telefon või tahvelarvuti) lugemiseks peate installeerima selle tasuta rakenduse: PocketBook Reader (iOS / Android)

PC või Mac seadmes lugemiseks peate installima Adobe Digital Editionsi (Seeon tasuta rakendus spetsiaalselt e-raamatute lugemiseks. Seda ei tohi segamini ajada Adober Reader'iga, mis tõenäoliselt on juba teie arvutisse installeeritud )

Seda e-raamatut ei saa lugeda Amazon Kindle's.

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

Introduction

(4)

PART I WRITING IN DITA

(84)

Chapter 1 Topic-Based Writing in DITA

(14)

Books, Topics, and Webs of Information

(2)

Advantages of Writing in Topics for Writing Teams

(1)

Writers Can Work More Productively

(1)

Writers Can Share Content with Other Writers

(1)

Writers Can Reuse Topics

(1)

Writers Can More Quickly Organize or Reorganize Content

(1)

Reviewers Can Review Small Groups of Topics Instead of Long Books

(1)

DITA Topic Types

(2)

Task Orientation

(3)

Task Analysis

(2)

Minimalist Writing

(2)

Know Your Audience

(1)

Remove Nonessential Content

(1)

Focus on User Goals, Not Product Functions

(1)

To Wrap Up

(1)

Topic-Based Writing Checklist

(1)

Task Analysis Form

(2)

Chapter 2 Task Topics

(20)

Separate Task Information from Conceptual or Reference Information

(1)

Write One Procedure per Topic

(1)

Create Subtasks to Organize Long Procedures

(1)

Task Components and DITA Elements

(16)

Titling the Task: <title>

(1)

Introducing the Task: <shortdesc>

(1)

Adding More Background Information: <context>

(1)

Describing Prerequisites: <prereq>

(2)

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

(7)

Concluding the Task: <example>, <postreq>, and <result>

(4)

Task Topic Checklist

(2)

Chapter 3 Concept Topics

(10)

Describe One Concept per Topic

(1)

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

(1)

Separate Task Information from Conceptual Information

(1)

Concept Components and DITA Elements

(6)

Titling the Concept Topic: <title>

(1)

Introducing the Concept Topic: <shortdesc>

(1)

Writing the Concept: <conbody>

(1)

Organizing the Concept: <section>

(1)

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

(3)

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

(1)

Highlighting New Terms: <term>

(1)

To Wrap Up

(1)

Concept Topic Checklist

(1)

Chapter 4 Reference Topics

(12)

Describe One type of Reference Material per Topic

(1)

Organize Reference Information Effectively

(1)

Format Reference Information Consistently

(1)

Reference Components and DITA Elements

(8)

Titling the Reference topic: <title>

(1)

Introducing the Reference Information: <shortdesc>

(1)

Organizing the Reference Information: <section>

(2)

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

(2)

Adding Lists: <ul> and <dl>

(1)

Creating Syntax Diagrams: <refsyn> and <syntaxdiagram>

(1)

To Wrap Up

(1)

Reference Topic Checklist

(2)

Chapter 5 Short Descriptions

(26)

The <shortdesc> Element

(3)

How the Short Description Is Used

(3)

Guidelines for Writing Effective Short Descriptions

(9)

Briefly State the Purpose of the Topic

(1)

Include a Short Description in Every Topic

(1)

Use Complete, Grammatical Sentences

(1)

Don't Introduce Lists, Figures, or Tables

(1)

Keep Short Descriptions Short

(4)

Short Descriptions for Task, Concept, and Reference Topics

(6)

Task Topic Short Descriptions

(4)

Concept Topic Short Descriptions

(1)

Reference Topic Short Descriptions

(1)

Writing Short Descriptions for Converted Content

(1)

The <abstract> Element

(3)

Using More DITA Elements in the Topic Introduction

(1)

Including Multiple Short Descriptions

(1)

To Wrap Up

(1)

Short Description Examples

(2)

Short Description Checklist

(2)

PART II ARCHITECTING CONTENT

(112)

Chapter 6 DITA Maps and Navigation

(18)

DITA Map Structure

(1)

Relationships Between Topics

(1)

Information Organization

(4)

Information Modeling

(1)

Benefits of Information Modeling

(1)

Building Information Models

(1)

Bookmaps

(1)

Submaps

(3)

DITA Map Ownership

101

(1)

Reference Non-DITA Content

101

(1)

Include Relationship Tables in DITA Maps

101

(1)

Override Topic Titles and Short Descriptions

102

(1)

Navigation Titles

102

(1)

Short Descriptions

102

(4)

Provide Unique Short Descriptions for Reused Topics

103

(2)

Provide Short Descriptions for Links to Non-DITA Content

105

(1)

Suppressing Topics from the Table of Contents

106

(1)

Suppressing Content from PDF Output

106

(1)

Suppressing Content from HTML Output

107

(1)

To Wrap Up

107

(1)

Navigation and DITA Maps Checklist

108

(1)

Chapter 7 Linking

109

(34)

Hierarchical Links

109

(2)

Inline Links

111

(5)

Link to Prerequisite and Postrequisite Information

113

(1)

Avoid Inline Links to Tables and Figures in a Topic

114

(1)

Create Inline Links to Repeated Steps

115

(1)

Create Inline Links to High-Level Tasks

115

(1)

Control How Links Are Displayed

116

(1)

Related Links

117

(6)

Relationship Tables

118

(4)

Implementing Relationship Tables

122

(1)

Collection Types

123

(10)

Sequence Collection Type

124

(3)

Choice Collection Type

127

(1)

Unordered Collection Type

128

(1)

Family Collection Type

129

(1)

Determining Which Collection Type to Use

130

(1)

Collection Types in Relationship Tables

131

(2)

Links Created with the Importance Attribute

133

(1)

Linking Scope

134

(4)

Local Links

136

(1)

External Links

136

(1)

Peer Links

137

(1)

Relative Paths for Links

138

(1)

Link Testing

138

(1)

To Wrap Up

138

(2)

Linking Checklist

140

(3)

Chapter 8 Metadata

143

(18)

Why Is Metadata Important?

143

(1)

Types of Metadata

144

(10)

Index Entries

145

(4)

Conditional Processing Attributes

149

(1)

Importance, Status, and Translate Metadata Attributes

150

(1)

Topic Metadata

150

(2)

DITA Map Metadata

152

(2)

Custom Metadata

154

(1)

Metadata Inheritance

155

(3)

To Wrap Up

158

(1)

Metadata Checklist

158

(3)

Chapter 9 Conditional Processing

161

(22)

Conditional Processing Attributes

163

(1)

Creating a Conditional Processing Scheme

164

(2)

Example of a Conditional Processing Scheme

164

(2)

Applying Conditional Processing Attributes

166

(7)

Applying Conditions to Content in Topics

166

(3)

Applying Conditions to DITA Maps and Relationship Tables

169

(2)

Excluding and Including Content

171

(1)

Flagging Content

171

(2)

Multiple and Compound Conditions

173

(5)

Multiple Conditions

174

(1)

Compound Conditions

174

(1)

Processing Logic for Multiple and Compound Conditions

174

(4)

Identifying Applied Conditional Values

178

(1)

Testing Your Scheme

179

(1)

Improving Content Retrievability for the Writing Team

179

(1)

To Wrap Up

179

(1)

Conditional Processing Checklist

180

(3)

Chapter 10 Content Reuse

183

(18)

Benefits of Reuse

183

(1)

Ways to Reuse Content

184

(1)

Reusing Elements by Using Content References

184

(8)

Conref Attribute

187

(3)

Phrase-Level Reuse

190

(1)

Designated Source Files for Conrefs

190

(2)

Reusing Topics

192

(2)

Copy-to Attribute

192

(2)

Reusing DITA Maps

194

(1)

Reusing Content from Non-DITA Sources

195

(1)

Writing for Reuse

195

(1)

Deciding Which Content to Reuse

196

(2)

Step 1 Analyze Your Content

197

(1)

Step 2 Identify Duplicate and Near Duplicate Content

197

(1)

Step 3 Address the Duplication

197

(1)

Step 4 Reorganize and Rewrite for Reuse

197

(1)

Step 5 Implement the Reuse Strategy

197

(1)

Track Your Reuse

198

(1)

To Wrap Up

198

(1)

Reuse Checklist

199

(2)

PART III CONVERTING AND EDITING

201

(72)

Chapter 11 Converting Content to DITA

203

(26)

Conversion Goals

203

(1)

Create a Pilot Team

204

(1)

Conversion Process

204

(20)

Step 1 Assess the State of Your Content

205

(1)

Content Analysis Worksheet

205

(2)

Step 2 Plan the Conversion

207

(1)

Scheduling the Conversion

207

(1)

Converting the Content In-House or Hiring a Vendor

208

(1)

Starring Your Conversion Team

209

(1)

Deciding on a Conversion Strategy

210

(2)

Defining Your XML Standard

212

(1)

Establishing Graphics Formats

212

(2)

Establishing DITA File Requirements

214

(3)

Deciding What DITA Topic Types You Need

217

(1)

Establishing an Architecture for Your DITA Maps

218

(1)

Handling Special Structures in Your Source Files

219

(1)

Step 3 Prepare the Content for Conversion

219

(2)

Conversion Workshops

221

(1)

Step 4 Convert Your Source Files

222

(1)

Step 5 Address Postconversion Issues

222

(1)

Phase 1 Address <required-cleanup> Elements

222

(1)

Phase 2 Fix DITA Maps and Build Errors

222

(1)

Phase 3 Improve Topics

223

(1)

Phase 4 Check for Markup Problems and Do Code Reviews

223

(1)

Phase 5 Exploit DITA

224

(1)

Step 6 Evaluate the Conversion Process

224

(1)

To Wrap Up

224

(1)

Conversion Sizing Table

225

(1)

DITA Conversion Checklist

226

(3)

Chapter 12 DITA Code Editing

229

(30)

Code Reviews

230

(2)

Code Review Benefits

230

(2)

Identifying Code Reviewers

232

(1)

Limiting the Scope of the Review

232

(1)

Preparing for Code Reviews

233

(1)

Using Special Style Sheets for Revealing Problems in the Markup

233

(1)

Performing a Code Review

234

(21)

Step 1 Schedule the Code Review

234

(1)

Step 2 Submit the DITA Topics for Review

235

(1)

Step 3 Review the DITA Markup

235

(1)

Common Problems Found in Task Topics

236

(5)

Common Problems Found in Concept Topics

241

(5)

Common Problems Found in Reference Topics

246

(3)

Common Problems Found in All Topic Types

249

(5)

Common Problems Found in DITA Maps

254

(1)

Common Problems Found in Metadata

254

(1)

Step 4 Discuss Review Findings

254

(1)

Step 5 Complete the Code Review

255

(1)

Code Reviews for Content Not in Topic Form

255

(1)

To Wrap Up

256

(1)

Code Review Checklist

257

(2)

Chapter 13 Content Editing

259

(14)

Defining, Scheduling, and Submitting Content Edits

260

(3)

Defining the Types of Content Edits

260

(1)

Scheduling the Edits

261

(1)

Submitting Content for Editing

262

(1)

Providing Editorial Feedback

263

(5)

Inserting Draft Comments

263

(2)

Inserting XML Comments

265

(1)

Tracking Changes

266

(2)

Comparing Original and Edited Files

268

(1)

Editing the Content in DITA Topics and Maps

268

(2)

Editing DITA Topics

268

(1)

Editing DITA Maps

269

(1)

Editing the Output

270

(1)

To Wrap Up

270

(1)

Content Editing Checklist

271

(2)

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.

Lisainfo e-raamatute kohta

Püsilink: https://www.kriso.ee/db/97801324798062e.html

Märksõnad:

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

DRM piirangud

Kopeerimine (copy/paste):

Printimine:

Kasutamine:

Konto & seaded

Otsing

Otsingu andmebaas

Filtreeri tulemusi

Teemad E-raamatute teemad

Vali ostukorv