DITA 101: Fundamentals Of DITA For Authors And Managers
Cover
AcknowledgementsThis was truly a group effort. I’d like to thank Steve Manning andCharles Cooper for all their assistance in putting this book together.I would also like to thank Rhonda Truitt and Laurel Simmons whoprovided edits in a very tight time frame.We would also like to thank the vendors for providing us with copiesof their editors to use to capture examples and create content. Adobe FrameMakerJustSystems XMetaLPTC Arbortext EditorQuark Dynamic Publishing Solution for Technical Publications 2009 The Rockley Group Inc. All rights reserved. No part of thisbook may be used or reproduced in any manner whatsoever withoutwritten permission except in the case of credited brief quotationsembedded in articles, reviews and presentations.ISBN 978-0-557-07291-0For information, contact:The Rockley Group Inc.,Email: moreinfo@rockley.comWebsite: www.rockley.comwww.dita101.com
ForewordThe pace at which technological innovation occurs is amazing. The last 20years have been jam-packed with paradigm-shifting technological advancesthat have altered forever the way we create, manage, and deliverinformation. The personal computer, the World Wide Web, desktoppublishing, touch-screen mobile phones, interactive television, socialnetworks, and wireless connectivity have transformed not only the wayconsumers interact with content, but these advances have also altered theway professional communicators work.Nowhere are these changes more evident than in the world of technicalcommunication. Technical writers and editors have been forced – like it ornot – to move to a more formal method of creating content, often for aglobal audience. Gone are the days of the free-for-all approach to creatingtechnical documentation products one-at-a-time using desktop publishingtools. While this technique was the best method possible in the 80s and 90s,today, those who create user manuals, online help systems, and other typesof documentation are increasingly expected to take a more formal approachto content creation, utilizing content standards like the Darwin InformationTyping Architecture (DITA) - the subject of this book.The advent of the Extensible Markup Language (XML) and rapid adoptionof topic-based content standards like DITA have forced us to separatecontent from format and end our addiction to desktop publishing. Today,technical communicators must learn to write modular, topic-based,context-independent content using a new breed of authoring tools. It's notan easy change for many. The resources available are often poorlyconceived, confusing, jargon-laden collections of information that don'tmake learning new skills and techniques easy. In fact, they make thingsmuch harder than they need be.That's why DITA 101 by Ann Rockley, Steve Manning and Charles Cooperis such an important work. Simple, easy-to-understand, and loaded withpractical examples that resonate with technical communicators, Rockleyand team have consolidated years of experience helping folks just like youmake the move from unstructured content creation to DITA. This work isthe result of their efforts and a valuable contribution to the technicalcommunication literature.Go ahead, take a peek. It's not as scary as you might think.Scott Abel, The Content Wrangler
ivDITA 101
Table of contentsWhat is DITA? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .Understanding the name . . . . . . . . . . . . . . . . . . . . . . . . . . . . .Architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .Information Typing. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .Darwin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .Topics, the building blocks of DITA . . . . . . . . . . . . . . . . . . . . .Maps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .Reuse . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .Content is separate from format . . . . . . . . . . . . . . . . . . . . . . . .Dita defined . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .DITA Open Toolkit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .11123445567The value of structure in content . . . . . . . . . . . . . . . . . . . . . . . . 9Recipe 1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10Recipe 2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11Recipe 3 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12The importance of structuring content . . . . . . . . . . . . . . . . . . 13Benefits of structured content . . . . . . . . . . . . . . . . . . . . . . 13Structured authoring guidelines . . . . . . . . . . . . . . . . . . . . . . . 14Reuse: Today’s best practice . . . . . . . . . . . . . . . . . . . . . . . . . .Why reuse content? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .Reduced development, review and maintenance . . . . . . .Translation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .Increased consistency . . . . . . . . . . . . . . . . . . . . . . . . . . . .Rapid reconfiguration . . . . . . . . . . . . . . . . . . . . . . . . . . . .Real world examples of the benefits of reusing content . .Processes of reuse . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .Opportunistic reuse . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .Systematic reuse . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .Types of reuse . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .Topic-based reuse. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .Fragment-based reuse . . . . . . . . . . . . . . . . . . . . . . . . . . .Filtered reuse. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .Variable reuse . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .191920202122222323232424242729Topics and maps – the basic building blocks of DITA . . . . . .Generic topic . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .Title . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .Short description/abstract . . . . . . . . . . . . . . . . . . . . . . . . .Prolog (for metadata). . . . . . . . . . . . . . . . . . . . . . . . . . . . .3131323233
viDITA 101Topic body . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .Related links . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .A sample topic . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .Concept . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .Task . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .Task example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .Map . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .Bookmap . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .343435373738414143A day in the life of a DITA author . . . . . . . . . . . . . . . . . . . . . . .Approaches to planning and developing content in DITA . . .Using maps as an outlining tool . . . . . . . . . . . . . . . . . . . . . . .What is a topic . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .Writing structured content . . . . . . . . . . . . . . . . . . . . . . . . . . .4545454648Planning for DITA . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .The plan . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .Content analysis . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .Physical analysis vs. programmatic analysis of reuse. . . .Developing a unified content strategy . . . . . . . . . . . . . . . .Roles and responsibilities . . . . . . . . . . . . . . . . . . . . . . . . . . . .Content Coordinator (new) . . . . . . . . . . . . . . . . . . . . . . . .Information Architect (new) . . . . . . . . . . . . . . . . . . . . . . . .DITA Technologist (new) . . . . . . . . . . . . . . . . . . . . . . . . . .Authors (modified role) . . . . . . . . . . . . . . . . . . . . . . . . . . .Content Owners (modified role). . . . . . . . . . . . . . . . . . . . .Editors (modified role) . . . . . . . . . . . . . . . . . . . . . . . . . . . .Content conversion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .Training and consulting . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5151515252535556575858595959Metadata . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .What is metadata and why is it important? . . . . . . . . . . . . . . .Prolog Metadata in DITA . . . . . . . . . . . . . . . . . . . . . . . . . . . .Publication metadata . . . . . . . . . . . . . . . . . . . . . . . . . . . . .Management metadata . . . . . . . . . . . . . . . . . . . . . . . . . . .Qualification metadata. . . . . . . . . . . . . . . . . . . . . . . . . . . .Selection attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .Relationship to other types of metadata (Dublin Core) . . . . .Metadata in taxonomy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .Metadata and your content management system . . . . . . . . .61616667676868697071DITA and technology . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73Authoring . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73
Table of contentsviiThe authoring interface . . . . . . . . . . . . . . . . . . . . . . . . . . .Text handling capabilities . . . . . . . . . . . . . . . . . . . . . . . . .DITA support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .Component content management system (CCMS) . . . . . . . .Support for DITA . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .Support for reuse. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .Support for translation . . . . . . . . . . . . . . . . . . . . . . . . . . .Publishing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .7474747677777878The “advanced” stuff . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .Domains . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .Conrefs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .Selection attributes (conditional content) . . . . . . . . . . . . . . . .Relationship tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .Specialization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .Why specialize DITA? . . . . . . . . . . . . . . . . . . . . . . . . . . . .So should you specialize DITA? . . . . . . . . . . . . . . . . . . . .8181828487899095Appendix A: DITA topic quick reference . . . . . . . . . . . . . . . . . 97Concept . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98Task . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105Appendix B - Prolog Metadata . . . . . . . . . . . . . . . . . . . . . . . . 107Appendix C: A history of DITA . . . . . . . . . . . . . . . . . . . . . . . .The origins . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .Why XML in content creation? . . . . . . . . . . . . . . . . . . . . . . .XML and structured content . . . . . . . . . . . . . . . . . . . . . .With all that, why do we need DITA? . . . . . . . . . . . . . . . . . .Design goals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .Benefits of DITA . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .Alternatives to DITA . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .DocBook . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .S1000D . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .What is XML? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .But what IS XML? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .What do XML Tags Do? . . . . . . . . . . . . . . . . . . . . . . . . . . . .Comparing XML and HTML . . . . . . . . . . . . . . . . . . . . . . . . .A procedure in HTML . . . . . . . . . . . . . . . . . . . . . . . . . . .Advantages of XML? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .An example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .DTDs and schemas . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .Advantages of schemas over DTDs? . . . . . . . . . . . . . . 22122123
viiiDITA 101Separation of content and format . . . . . . . . . . . . . . . . . . . . . 125XSL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129
IntroductionMore and more companies are either adopting DITA or thinkingabout adopting it, yet surprisingly, there are very few resourceswritten in plain English for those who want to learn about it. Many ofthe existing resources are very technical in nature - notably the DITAspecification. Often you might find yourself asking “how do I find outmore about that?” and the response is, “it is all in the spec.”And there’s the problem - the DITA specification is just that - atechnical specification describing the standard. It wasn’t designed as ateaching tool and it shouldn’t be used as one. The spec is something aDITA technologist should read, not the average writer or manager.The good news is that we’ve designed DITA 101 for writers andmanagers. We’ve taken our years of experience helping organizationsto move to DITA and distilled it into an easy-to-read andunderstandable format. And since the move to DITA often goeshand-in-hand with an organization’s adoption of contentmanagement, we’ve made sure that our expertise in developingeffective content, reuse, and their appropriate strategies areintegrated here to give you everything you need to know tounderstand DITA from a author’s or manager’s viewpoint. What is DITA provides a definition of DITA and explains its keyfeatures. The value of structure in content explains how to analyze contentfor structure and uses recipes to illustrate the concepts ofstructure and structured writing. Reuse: Today’s best practice presents the benefits of reuse andprovides an understanding of all the types of reuse that DITAsupports. Topics and maps takes you through the building blocks of DITA. A day in the life of a DITA author helps to illustrate how an authorwould develop a content outline, create topics and writestructured content. Planning for DITA provides insights into how to most effectivelyplan for DITA and the changes in roles and responsibilities.
xDITA 101 Metadata introduces the concepts of metadata, an oftenoverlooked and misunderstood topic, and gives insight into themetadata that DITA supports. DITA and technology introduces some of the key DITA featuresthat authoring, content management and publishing systemsshould support. The advanced stuff contains our insight on such topics asdomains, conrefs, selection attributes, relationship tables andspecialization. Appendix A and B provide a quick reference to topic elements andprolog metadata respectively. Appendix C gives more background on XML if you would like todelve in deeper.Examples are used throughout to illustrate the concepts.We hope you find DITA 101 useful.
Reuse: Today’s best practiceContent reuse is the practice of using existing components of contentto develop new “documents.” Text-based materials are the easiest toreuse. It’s easier to reuse graphics, charts and media in their entiretythan it is to use portions of them, but it is possible to create reusablemedia. We focus on text-based reuse in this book.Most organizations already reuse content by copying and pastingcontent wherever they need it. This works well until the content hasto be updated when it’s usually very time-consuming to find andchange all those places where the content has been used. Not onlydoes this waste time but you run the real danger of missing someinstances of content which can result in inconsistencies andinaccuracies.Then again, a whole lot of organizations write content, rewritecontent and then rewrite again! This may be because one of thefollowing is true: Multiple people are writing the same or very similar content anddo not know that someone else has already written it. Everyone feels that their customer and content requirements aredifferent, so the content has to be rewritten. Different authors may be assigned to different media (e.g., oneauthor is responsible for Help, while another is responsible forprint and yet another for training materials). Some authors feel it’s just too hard to find what is already written,and therefore, it’s much faster to write the content from scratch.Why reuse content?When we write content for technical documents, particularly whenwe have product suites, product solutions and common functionality,there are many good reasons for reusing content.Reusing content can provide a dramatic improvement in the waycontent is created in an organization. Improvements includeincreased quality and consistency, reduced time and costs fordevelopment and maintenance and reduced costs of translation.
20DITA 101Reduced development, review and maintenanceDevelopment costs are reduced because the amount of content aauthor has to create is reduced. Authors do not have to research andwrite it again, they simply reuse it.In addition to taking less time to create the content, less time isrequired to review the content. When approved content is reused, it’snot necessary to review it again. This frees up reviewers to do their“real job.”When content is reused, everywhere that content is reused isautomatically updated.ROI: Is based on the percentage of reuse. Typically this is a minimumof 25%, but could be as high as 80%, depending upon how the contentis reused (e.g., across types of information such as Help and print, thepercentage of reuse is often very high and is also high acrossvariations of a product).TranslationYou can significantly reduce the cost of translation through reuse.Translation memory systems (TMS) use pattern matching to matchcontent that has already been translated so the content does not haveto be translated again. Each time content is sent for translation, it’srun through the translation memory tool to identify content strings(text) that have been already translated and the existing translation isreused. As you plan for reuse, you ensure that more content is reused,and therefore translation costs are reduced even further. In addition,if content has already been translated, only new or changed contentneeds to be sent out for translation which reduces costs even more.Translated content can also be rapidly reconfigured and brand newinformation products can even be delivered from existing elementsthat have already been translated, without ever having to send thatcontent to translation and pay additional costs.The less easily measured benefits of consistent structure, consistentterminology and standardized writing guidelines that reuse requiresalso help to reduce the cost of translation.
Reuse: Today’s best practice21Often, a large cost in translation is in reformatting content.Frequently, content must be converted from the original sourceformat (e.g., Help, FrameMaker, HTML) to RTF (rich text format)before it can be translated. When
DITA technologist should read, not the average writer or manager. The good news is that we’ve designed DITA 101 for writers and managers. We’ve taken our years of expe rience helping organizations to move to DITA a
The DITA Open Toolkit (DITA-OT) is an open-source implementation of the OASIS DITA specification, which is developed by the OASIS DITA Technical Committee. The DITA-OT is a set of Java-based, open-source tools and Ant scripts that transform DITA content (maps and topics) into deliverable f
According to the DITA Exchange product team, the map viewer is the most frequently accessed UI by SMEs and serves as a popular entryway into topic creation, review, and revision. Technically, the map viewer is not part of the DITA Exchange editor, rather it is part of DITA Exchange’s l
LightWeight DITA seems to be quite promising in improving the spread of DITA outside the . Introduction When studying technical writing, authoring in DITA has become an unavoidable course. . (OASIS) to release it to the public. In fact, IBM realized that it “would be more useful if [it] could actually have this spread to other firms that .
OASIS Darwin Information Typing Architecture (DITA) TC Chair(s): Don Day Editor(s): Michael Priestley Robert D. Anderson JoAnn Hackos Related Work: This specification replaces or supercedes: OASIS DITA Language Specification Version 1.0 This specification is related to: OASIS DITA Architectural S
DITA Architectural Specification v1.0 1.1 approved as an OASIS Standard in August 2007. DITA Language Reference v1.1 DITA Architectural Specification v1.1 1.2 approved as an OASIS Standard in December 2010. DITA Specification v1.2 Current version of
Man y DITA authoring and publishing tools come with standard transformers for most common delivery formats, such as PDF, RTF and HTML. The DITA Open Toolkit, an open source collection of utilities and documentation to help writers work with DITA, includes basic transformers for PDF, RTF, HTML, DocBook, Eclipse Help, and Microsoft HTML Help.
Verkehrszeichen in Deutschland 05 101 Gefahrstelle 101-10* Flugbetrieb 101-11* Fußgängerüberweg 101-12* Viehtrieb, Tiere 101-15* Steinschlag 101-51* Schnee- oder Eisglätte 101-52* Splitt, Schotter 101-53* Ufer 101-54* Unzureichendes Lichtraumprofil 101-55* Bewegliche Brücke 102 Kreuzung oder Einmündung mit Vorfahrt von rechts 103 Kurve (rechts) 105 Doppelkurve (zunächst rechts)
Adventure tourism is a “ people business ”. By its very nature it involves risks. Provid-ers need to manage those risks, so partici-pants and staff stay safe. The consequences of not doing so can be catastrophic. ISO 21101 : Adventure tourism – Safety management systems – A practical guide for SMEs provides guidance for small businesses to design and implement safety management systems .
