Home > Store

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

Rough Cuts

  • Available to Safari Subscribers
  • About Rough Cuts
  • Rough Cuts are manuscripts that are developed but not yet published, available through Safari. Rough Cuts provide you access to the very latest information on a given topic and offer you the opportunity to interact with the author to influence the final publication.

Not for Sale

Description

  • Copyright 2011
  • Pages: 288
  • Edition: 1st
  • Rough Cuts
  • ISBN-10: 0-13-237430-7
  • ISBN-13: 978-0-13-237430-9

This is the Rough Cut version of the printed book.

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

Sample Content

Table of 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 Co

Updates

Submit Errata

More Information