1. IBM User Technologies | April 2005 | © 2005 IBM Corporation Interoperable Extensibility Through DITA Topic and Domain Types Erik Hennum IBM DITA Domains Architect

2. IBM User Technologies Extensibility Through DITA Topic and Domain Types © 2005 IBM Corporation 2 The discussion ahead  What is DITA? – Why was DITA developed?  What is specialization? – How do you extend DITA?  What are Topic types? Domain types? Maps and map domains?

3. IBM User Technologies Extensibility Through DITA Topic and Domain Types © 2005 IBM Corporation 3 What is DITA?

4. IBM User Technologies Extensibility Through DITA Topic and Domain Types © 2005 IBM Corporation 4 History of Markup 1970s: ISIL 1980s: BookMaster IPF 1990s: SGML, HTML 2000+ XML-based semantics Need for Change Printed Books Limited reuse Single purpose Printed and online Books, online help Monolithic Book-Centered DTD Shorter cycles Fewer people, Decreasing learning curves, Faster, better, cheaper Components, Multiplatform, Integrated systems Web-deployed products Partner and OEM use of information Online information, Webs, printable & Printed books Information Architecture

5. IBM User Technologies Extensibility Through DITA Topic and Domain Types © 2005 IBM Corporation 5 The Vision (1998/1999) Multiple formats

6. IBM User Technologies Extensibility Through DITA Topic and Domain Types © 2005 IBM Corporation 6 Core design principles of DITA  Topic orientation Each content object covers one subject for a specific purpose  Topic granularity Content objects are assembled into information sets  Strong typing Types enforce structures specific to the content semantics  Type specialization Types extend more basic types to model new kinds of information  Common base class The top-level generic type provides interoperability and fallback for all topics

7. IBM User Technologies Extensibility Through DITA Topic and Domain Types © 2005 IBM Corporation 7 What is DITA specialization?

8. IBM User Technologies Extensibility Through DITA Topic and Domain Types © 2005 IBM Corporation 8 The motivation for specialization  The realization Generic XML solutions are not specific to your needs Knowledge representation is strongly related to industry, community, and organization culture  The existing tradeoff The more useful your XML markup is to you, the more it will cost you and the fewer people will share the costs

9. IBM User Technologies Extensibility Through DITA Topic and Domain Types © 2005 IBM Corporation 9 Specializing a topic type  The specialized topic type for procedural instructions works to Guide the writer Enforce the structure Declare the semantics In short, make the content easier to understand, validate, and process General topic Installing a hard drive Unscrew the cover. The drive bay... Insert the drive... If you feel... Specialized task Installing a hard drive Unscrew the cover. The drive... Insert the drive... If you feel resistance...

10. IBM User Technologies Extensibility Through DITA Topic and Domain Types © 2005 IBM Corporation 10 Specialization rules  Design constraint – extension by restriction The content model must be a specialized subset of the base model As a result, every instance of the derived model is valid for the base model A good fit for discourse because text tends toward loose content models  Declare the specialization ancestry with the class attribute in the schema DTD: XML Schema: The ol element in the topic module is the base of the steps element in the task module  Process by matching the element type in the class attribute XSLT idiom: Specializations can rely on the base processing or override.

11. IBM User Technologies Extensibility Through DITA Topic and Domain Types © 2005 IBM Corporation 11 Implementing a specialized element The class attribute identifies the module and type ancestry Base processing applies by default The specialization can override base processing topic design module:... task design module:... topic processing module:... task processing module:... Every element has an architectural class attribute

12. IBM User Technologies Extensibility Through DITA Topic and Domain Types © 2005 IBM Corporation 12 Generalizing to the base type (casting)  An automated process can preserve the content but convert from specialized to general markup: To send content to someone who doesn’t have your specialized markup To retire specialized markup but keep the content To provide content to a tool that understands only element names and not the DITA class attribute Tutorial my types MaintenanceProcedure your types Task our types

13. IBM User Technologies Extensibility Through DITA Topic and Domain Types © 2005 IBM Corporation 13 What is a DITA topic type?

14. IBM User Technologies Extensibility Through DITA Topic and Domain Types © 2005 IBM Corporation 14 Specialization hierarchy for topic types Topic ConceptTask Tutorial Java APIC++ API CommandMessage Reference API The topic type provides the coarse structure and semantics for content Event announcement Insurance claim form Use case specification or or...

15. IBM User Technologies Extensibility Through DITA Topic and Domain Types © 2005 IBM Corporation 15 Parts of a DITA topic 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 and labels Processable properties Content structure for the topic type

16. IBM User Technologies Extensibility Through DITA Topic and Domain Types © 2005 IBM Corporation 16 A hybrid topic with both data and discourse content How to compose an eNote... To compose an eNote, you...... Specialized data Discourse

17. IBM User Technologies Extensibility Through DITA Topic and Domain Types © 2005 IBM Corporation 17 What is a DITA vocabulary domain?

18. IBM User Technologies Extensibility Through DITA Topic and Domain Types © 2005 IBM Corporation 18 Specialization of vocabulary domains  Use a domain in many topic types Defines metadata properties, kinds of names, or text structure for a subject area Fine-grained structure and semantics  DITA core domains programming: apiname, codeph, codeblock, … software: cmdname, filepath, varname, … user interface: wintitle, uicontrol, … highlighted phrases: b, i, u, sup, sub, …  Create new domains for subject areas Telco, Semiconductor, Financial, Insurance, Retail, Legal, Life Sciences, … Task topic type Software domain UI domain Programming domain Highlighting domain Domains as blades for topic typesDomain inheritance UI domain Web UI domain topic elements

19. IBM User Technologies Extensibility Through DITA Topic and Domain Types © 2005 IBM Corporation 19 Pluggability of topic and domain modules  To create a document type, you plug in specialization modules For financial services software, you might include The task type The UI domain A new domain that you created for the vocabulary of the financial industry The highlighting domain – if you are a pragmatist Task topic type Financial domain UI domain Highlighting domain ?

20. IBM User Technologies Extensibility Through DITA Topic and Domain Types © 2005 IBM Corporation 20 Example of some DITA domain phrases Amortizing the loan... Choose the Amortizer menu item The Amortizer window displays. Enter the term. You must choose one of the options. UI domain Financial domain (possible future) Highlighting domain

21. IBM User Technologies Extensibility Through DITA Topic and Domain Types © 2005 IBM Corporation 21 What is a DITA map?

22. IBM User Technologies Extensibility Through DITA Topic and Domain Types © 2005 IBM Corporation 22 Topics reused in information sets Topic 1 Topic 4 Topic 2 Topic 3  Deliverables select topics from a pool Deliverable 1 uses topics 1 and 4 Deliverable 2 uses topics 2 and 4 Neither deliverable uses topic 3

23. IBM User Technologies Extensibility Through DITA Topic and Domain Types © 2005 IBM Corporation 23 Working with DITA maps  A DITA map applies context to a set of topics Assembles an information set for a purpose such as a deliverable Supports reuse of topics in different structures in multiple information sets  Sets the contextual properties of topics Titles and metadata A topic can be advanced in one set and basic in another  Specifies relationships between the topics Eclipse help JavaHelp HTMLHelp web pages books topicsmap deliverables

24. IBM User Technologies Extensibility Through DITA Topic and Domain Types © 2005 IBM Corporation 24 Relationships between topics managed in a map  Hierarchical structures Book nesting or web or help navigation – but also parts explosion, …  Group structures Related links – but also any distributed or sequential association  Tabular structures Related links – but also any matrixed association between topics hierarchygrouptable

25. IBM User Technologies Extensibility Through DITA Topic and Domain Types © 2005 IBM Corporation 25 Examples of topic references in a DITA map <topicref href="installoverview.dita" audience="admin">......... Contextual property Group relationships Hierarchical relationships Tabular relationships

26. IBM User Technologies Extensibility Through DITA Topic and Domain Types © 2005 IBM Corporation 26 Example of possible map domains  Pluggable vocabularies for maps  Specialized references to topics Specify the topic role within a set of topics Specify the topic type for validation  Specialized group or tabular structures The semantics of the relationship between the referenced topics......... Role for referenced topic Semantic table structure Type of referenced topic

27. IBM User Technologies Extensibility Through DITA Topic and Domain Types © 2005 IBM Corporation 27 The DITA vision: a platform for collaboration  Content markup that’s specific to the subject area Marketing event announcements, Development functional specifications, or Real estate appraisal forms  Shared markup modules Across industry segments or communities and between partners  Local markup for the organization Agree on the shared basics, diverge on the local idiosyncrasies  Install the specialization modules, assemble the document types, and go

28. IBM User Technologies Extensibility Through DITA Topic and Domain Types © 2005 IBM Corporation 28 Summary of business value  Faster time to value – create solution offering across industry stacks or within your business with different components  Increased reuse – of content by referencing topics in many map contexts – of designs by providing only the specialized delta on the general base – of processing by overriding the base only where needed  Investment protection – because of automated fallback to more general markup

29. IBM User Technologies Extensibility Through DITA Topic and Domain Types © 2005 IBM Corporation 29 DITA and the Open Community  The DITA Standard at OASIS Contributed in 2004 DITA 1.0 specification – Committee Recommendation DITA Technical Committee includes: XML tool vendors (Arbortext, Blast Radius, Idiom, Rascal, Syntext) Consultants (Comtech, Innodata, Mulberrytech) Companies (BMC, Boeing, IBM, Intel, Lucent, Nokia, Oracle, Sun) Education and government (National Library of Medicine, US Department of Defense)  The DITA Open Toolkit at SourceForge Successor to public toolkit published through IBM DeveloperWorks Reference implementation – usable for production, ongoing enhancement Other community-contributed utilities Community specialization modules Samples and demos of DITA capabilities

30. IBM User Technologies Extensibility Through DITA Topic and Domain Types © 2005 IBM Corporation 30 Where next?  Learn more about DITA OASIS – http://www.oasis-open.org/committees/dita Cover page – http://xml.coverpages.org/dita.html  Where do we take DITA together? Join the dialog on the DITA forum – http://groups.yahoo.com/group/dita-users/  Download the DITA Open Toolkit http://sourceforge.net/projects/dita-ot/

31. IBM User Technologies Extensibility Through DITA Topic and Domain Types © 2005 IBM Corporation 31 Backup

32. IBM User Technologies Extensibility Through DITA Topic and Domain Types © 2005 IBM Corporation 32 DITA defined  Darwin: DITA utilizes principles of inheritance for specialization  Information Typing: DITA was 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

33. IBM User Technologies Extensibility Through DITA Topic and Domain Types © 2005 IBM Corporation 33 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