1 / 33

Interoperable Extensibility Through DITA Topic and Domain Types

Interoperable Extensibility Through DITA Topic and Domain Types. Erik Hennum IBM DITA Domains Architect. 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?.

sophia-strong
Download Presentation

Interoperable Extensibility Through DITA Topic and Domain Types

An Image/Link below is provided (as is) to download presentation Download Policy: Content on the Website is provided to you AS IS for your information and personal use and may not be sold / licensed / shared on other websites without getting consent from its author. Content is provided to you AS IS for your information and personal use only. Download presentation by click this link. While downloading, if for some reason you are not able to download a presentation, the publisher may have deleted the file from their server. During download, if you can't get a presentation, the file might be deleted by the publisher.

E N D

Presentation Transcript

  1. Interoperable ExtensibilityThrough DITA Topic and Domain Types Erik Hennum IBM DITA Domains Architect

  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. What is DITA?

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

  5. The Vision (1998/1999) Multiple formats

  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. What is DITA specialization?

  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. Specialized task <task id="installstorage"> <title>Installing a hard drive</title> <taskbody> <steps> <step><cmd>Unscrew the cover.</cmd> <stepresult>The drive...</stepresult> </step> <step><cmd>Insert the drive...</cmd> <info>If you feel resistance...</info> </step> </steps> </taskbody> </task> Specializing a topic type General topic <topic id="installstorage"> <title>Installing a hard drive</title> <body> <ol> <li><ph>Unscrew the cover.</ph> <itemgroup>The drive bay...</itemgroup> </li> <li><ph>Insert the drive...</ph> <itemgroup>If you feel...</itemgroup> </step> </ol> </body> </topic> • 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

  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: <!ATTLIST steps class CDATA "- topic/ol task/steps "> XML Schema: <xs:attribute ref="class" default="- topic/ol task/steps "/> 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: <xsl:template match="*[contains(@class,' topic/ol ')]"> Specializations can rely on the base processing or override.

  11. Implementing a specialized <steps> element Every element has an architectural class attribute topic design module: <!ELEMENT ol (%li;)+> ... <!ATTLIST ol class CDATA "- topic/ol "> <!ATTLIST li class CDATA "- topic/li "> task design module: <!ELEMENT steps (%step;)+> ... <!ATTLIST steps class CDATA "- topic/ol task/steps "> <!ATTLIST step class CDATA "- topic/li task/step "> topic processing module: <xsl:template match="*[contains(@class,' topic/ol ')]"> ... task processing module: <xsl:template match="*[contains(@class,' task/steps ')]"> ... The class attribute identifies the module and type ancestry Base processing applies by default The specialization can override base processing

  12. Task our types Tutorial MaintenanceProcedure my types your types 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

  13. What is a DITA topic type?

  14. Specialization hierarchy for topic types The topic type provides the coarse structure and semantics for content Topic Concept Task Reference Eventannouncement or Insuranceclaim form Tutorial Command API Message or Use casespecification or. . . C++ API Java API

  15. Parts of a DITA topic Identifier and labels <task id="installstorage"> <title>Installing a hard drive</title> <shortdesc>You open the box and insert the drive.</shortdesc> <prolog><metadata> <audience type="administrator"/> <keywords> <indexterm>hard drive</indexterm> <indexterm>disk drive</indexterm> </keywords> </metadata></prolog> <taskbody> <steps> <step><cmd>Unscrew the cover.</cmd> <stepresult>The drive bay is exposed.</stepresult> </step> <step><cmd>Insert the drive into the drive bay.</cmd> <info>If you feel resistance, try another angle.</info> </step> </steps> </taskbody> </task> Processable properties Content structure for the topic type

  16. A hybrid topic with both data and discourse content <enote id="note1"> <subject>How to compose an eNote</subject> <notedetail> <noteheader> <From> <recipient href="sender@send.org"/> </From> <To> <recipient href="receiver@receive.org"/> </To> ... </noteheader> <notebody> <p>To compose an eNote, you ...</p> ... </notebody> </notedetail> </enote> Specialized data Discourse

  17. What is a DITA vocabulary domain?

  18. Specialization of vocabulary domains Domain inheritance Domains as blades for topic types topic elements Task topic type Software domain UI domain Programming domain UI domain Web UI domain Highlighting domain • 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, …

  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. Example of some DITA domain phrases UI domain <task id="amortizingloan"> <title>Amortizing the loan</title> ... <taskbody> <steps> <step><cmd>Choose the Amortizer menu item</cmd> <stepresult>The <wintitle>Amortizer</wintitle> window displays.</stepresult> </step> <step><cmd>Enter the <loanfactor>term</loanfactor>.</cmd> <info>You <b>must</b> choose one of the options.</info> </step> </steps> </taskbody> </task> Financial domain (possible future) Highlighting domain

  21. What is a DITA map?

  22. Topics reused in information sets Topic 1 Topic 2 Topic 3 Topic 4 • 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. Working with DITA maps Eclipse help JavaHelp HTMLHelp web pages books topics map deliverables • 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

  24. Relationships between topics managed in a map hierarchy group table • 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

  25. Examples of topic references in a DITA map Contextual property <map title="Enterprise web management"> <topicref href="installoverview.dita" audience="admin"> <topicref href="installdb.dita"> <topicref href="closeprograms.dita"/> <topicref href="runsetup.dita"/> ... <topicgroup collection-type="family"> <topicref href="installdb.dita"/> <topicref href="configuredb.dita"/> ... <reltable> <relrow> <relcell> <topicref href="installdb.dita"/> </relcell> <relcell> <topicref href="dbconcepts.dita"/> </relcell> ... </map> Hierarchical relationships Group relationships Tabular relationships

  26. Example of possible map domains Role for referenced topic <map> ... <howto href="dita-mapdomains.xml"> <taskref href="implementDomain.xml"/> ... <annotationRow> <publicCell> <topicref href="installdb.dita"/> </publicCell> <serviceCell> <topicref href="installfix.dita"/> </serviceCell> ... </map> Type of referenced topic Semantic table structure • 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

  27. The DITA vision: a platform for collaboration • Content markup that’s specific to the subject area Marketing event announcements, Development functional specifications, orReal 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. 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. 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. 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. Backup

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

More Related