IBM Corporate User Technologies | February 2004 | © 2004 IBM Corporation An Introduction to Darwin Information Typing Architecture: DITA

IBM Corporate User Technologies Introduction to DITA © 2004 IBM Corporation 2 Agenda  History of DITA – Why was DITA developed?  Introduction to DITA – What is DITA?  Benefits of DITA – Why should you care?

IBM Corporate User Technologies Introduction to DITA © 2004 IBM Corporation 3 What you will hear  DITA is about making life easier in the realm of technical writing For authors, for editors, for managers, for collaborators, for information architects, for developers supporting the teams, for customers  DITA is about reuse Focus on topic authoring based on an information architecture which supports recombination and specialization

IBM Corporate User Technologies Introduction to DITA © 2004 IBM Corporation 4 Background: Why DITA?

IBM Corporate User Technologies Introduction to DITA © 2004 IBM Corporation 5 History of markup in IBM

IBM Corporate User Technologies Introduction to DITA © 2004 IBM Corporation 6 Identify need – Historic convergences within IBM  IBM task force on information architecture  Technical writing community focus on Minimalism  W3C development of XML  Trend away from SGML (IBMIDDOC)  Recognized need for alternative Shorter development cycles Variability in HTML outputs Componentization of products Need for reuse

IBM Corporate User Technologies Introduction to DITA © 2004 IBM Corporation 7 Identify the need – Customer issues  Solutions, not products Integration of information  Information glut More meaningful information (role & task based)  Out-of-date information in books Updating and maintaining information  Reduce cost of deployment of information Provide information on-line  Reduce support costs Customize and update information

IBM Corporate User Technologies Introduction to DITA © 2004 IBM Corporation 8 Identify the need – The Vision (1998/1999)

IBM Corporate User Technologies Introduction to DITA © 2004 IBM Corporation 9 Address the problem – Charter XML Work Group  Appoint technical / thought lead  Recruit community technical leads Top of line knowledge Top of line passion  Define charter and scope  Extend into areas outside ownership to define boundaries  Offer competence to others Establish thought leadership Develop and enhance analytic skills

IBM Corporate User Technologies Introduction to DITA © 2004 IBM Corporation 10 Promise and Reality of XML  Promise Separate content from form: reuse content in different presentation media Use specific markup to describe your content Use standard solution to enable easy exchange of information  Reality – Generic XML Generic XML provides an SGML with simpler syntax but similar problems Generic solutions - not specific to needs Knowledge representation is strongly related to current corporate culture  Tradeoff The more useful your markup is to you, the more it will cost you and the fewer people will share the costs

IBM Corporate User Technologies Introduction to DITA © 2004 IBM Corporation 11 DITA designed to address trade-offs What is DITA?

IBM Corporate User Technologies Introduction to DITA © 2004 IBM Corporation 12 DITA defined  Darwin: DITA utilizes principles of inheritance for specialization  Information Typing: DITA was originally designed for technical information based on an information architecture of Concept, Task and Reference  Architecture: DITA is a model for extension both of design and of processes

IBM Corporate User Technologies Introduction to DITA © 2004 IBM Corporation 13 Core design principles of DITA  Topic orientation Discrete units of information covering a specific subject with a specific intent  Topic granularity Self-contained topics combine with other topics into information sets  Strong typing DTDs and schemas guarantee that DITA types follow identical information structures  Specialization Architecture for extending basic types to new types adapted for a particular use within an information set  Common base class Top-level "generic" base type provides “fallback” for all types

IBM Corporate User Technologies Introduction to DITA © 2004 IBM Corporation 14 The core DITA topic types – The “IT” in DITA topic concept task reference Provides background information that users need to know. Provides quick access to facts. Provides procedural details such as step-by-step instructions. A unit of information which is meaningful when it stands alone.

IBM Corporate User Technologies Introduction to DITA © 2004 IBM Corporation 15 DITA and reuse

IBM Corporate User Technologies Introduction to DITA © 2004 IBM Corporation 16 Reuse of content  Reuse flows from the topic-based paradigm  If content is authored as standalone topics Topics can be reused in different contexts Topics from multiple components can be integrated as a solution

IBM Corporate User Technologies Introduction to DITA © 2004 IBM Corporation 17 Working with DITA maps  A DITA map applies context to the topics  Organizes a set of topics in a hierarchy and sequence Different organization for different deliverables — not just different formats for the same content Can reuse the same topic with different collections of topics Can provide multiple views on the same topics: by product, by task, …  Sets properties of the topic at a position within the hierarchy Properties include the title and metadata Change the title relative to the parent topic Metadata can identify a topic as advanced for one deliverable and basic for another Eclipse help JavaHelp HTMLHelp web pages books

IBM Corporate User Technologies Introduction to DITA © 2004 IBM Corporation 18 Reuse of design  General types are rarely enough Requirements specific to organization or industry  Meet requirements with new elements New element specializes existing element New content is a subset of base content  Add only the deltas - still use the base  Designs are modular For instance, optional b and i highlighting

IBM Corporate User Technologies Introduction to DITA © 2004 IBM Corporation 19 Specializing from Topic to Task Small DTD additions to enforce document structure. May have no CSS or XSL process changes. topic title prolog metadata related-links body task title prolog metadata taskbody prereq context steps taskxmp result postreq step cmd, (info | substeps | tutorialinfo | xmp | choices)*, result? related-links topic title prolog metadata related-links body task title prolog metadata taskbody prereq context steps example result postreq step cmd, (info | substeps | tutorialinfo | stepxmp | choices|choicetable)*, stepresult? related-links

IBM Corporate User Technologies Introduction to DITA © 2004 IBM Corporation 20 From Task to Business Task Additional structure changes. businesstask title prolog metadata related-links btaskbody prereq context bsteps example result postreq step appstep appdesc task title prolog metadata taskbody prereq context steps taskxmp result postreq step cmd, (info | substeps | tutorialinfo | xmp | choices)*, result? related-links task title prolog metadata taskbody prereq context steps example result postreq step cmd, (info | substeps | tutorialinfo | stepxmp | choices|choicetable)*, stepresult? related-links

IBM Corporate User Technologies Introduction to DITA © 2004 IBM Corporation 21 Specializations from Topic Topic is the core. Each specialization is a delta in design, and if it needs special processing that's a delta too.

IBM Corporate User Technologies Introduction to DITA © 2004 IBM Corporation 22 Benefit of design reuse through specialization  No need to reinvent the base vocabulary - Create a module in 1/2 day with 10 lines vs. 6 months with 100s of lines; automatically pick up changes to the base  No impact from other designs that customize for different purposes - Avoid enormous, kitchen-sink vocabularies; Plug in the modules for your requirements  Interoperability at the base type - Guaranteed reversion from special to base  Reusable type hierarchies - Share understanding of information across groups, saving time and presenting a consistent picture to customers  Output tailored to customers and information - More specific search, filtering, and reuse that is designed for your customers and information not just the common denominator  Consistency - Both with base standards and within your information set  Learning support for new writers - Instead of learning standard markup plus specific ways to apply the markup, writers get specific markup with guidelines built in  Explicit support of different product architectural requirements - Requirements of different products and architectures can be supported and enforced, rather than suggested and monitored by editorial staff

IBM Corporate User Technologies Introduction to DITA © 2004 IBM Corporation 23 Reuse of processes  Base processing in extensible XSLT  Standard processing can be customized Override standard processing as needed  Processes for base elements apply to new specialized elements by default Can use base processing Can write custom processing if needed

IBM Corporate User Technologies Introduction to DITA © 2004 IBM Corporation 24 Specialized processes handle the delta for specialized topic types Base topic Task Concept Reference bcTask bcReference Specialization-specific processors Base processors Base and delta DTDs Base and delta processors Specialized processes

IBM Corporate User Technologies Introduction to DITA © 2004 IBM Corporation 25 Summary

IBM Corporate User Technologies Introduction to DITA © 2004 IBM Corporation 26 Summary of reuse  Reuse content through topics Author content as standalone information  Reuse designs through specialization Meet requirements specific to organization Keep interoperability with others  Reuse processing Customize only as needed

IBM Corporate User Technologies Introduction to DITA © 2004 IBM Corporation 27 Summary Benefits and Problems Solved Development challenges met Shorter development cycles Eliminate variability in HTML outputs Support componentization of products and need for reuse Deliver solution information, not product information Integration of information Information glut More meaningful information (role & task based) Out-of-date information in books Updating and maintaining information Reduce cost of deployment of information Provide information on-line Reduce support costs Customize and update information

IBM Corporate User Technologies Introduction to DITA © 2004 IBM Corporation 28 Backup Slides

IBM Corporate User Technologies Introduction to DITA © 2004 IBM Corporation 29 Epic Editor with DITA Maps Manage hierarchy Create new & edit Preview HTML & PDF Check out

IBM Corporate User Technologies Introduction to DITA © 2004 IBM Corporation 30 Epic Editor with DITA Topics Content edit Common elements Indexing, linking helpers

IBM Corporate User Technology An Introduction to DITA © 2004 IBM Corporation DITA topic example Installing a hard drive You open the box and insert the drive. hard drive disk drive Unscrew the cover. The drive bay is exposed. Insert the drive into the drive bay. If you feel resistance, try another angle. Identifier, title, and shortdesc Properties of the topic Type-specific content body Relationships to other topics

IBM Corporate User Technology An Introduction to DITA © 2004 IBM Corporation DITA map example <topichead navtitle="Installing" audience="admin"> Install products before configuring or using them. … A heading doesn’t have to have a topic Title and properties can be assigned in the map A topic can appear multiple times in the hierarchy The map organizes a set of topics in a hierarchy