An Introduction to Darwin Information Typing Architecture: DITA

1. An Introduction to Darwin Information Typing Architecture:DITA

2. Agenda • History of DITA – Why was DITA developed? • Introduction to DITA – What is DITA? • Benefits of DITA – Why should you care?

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

4. Background: Why DITA?

5. History of markup in IBM

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

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

8. Identify the need – The Vision (1998/1999)

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

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

11. DITA designed to address trade-offs What is DITA?

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

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

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

15. DITA and reuse

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

17. Working with DITA maps Eclipse help JavaHelp HTMLHelp web pages books • 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

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

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

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

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.

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

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

24. Specialized processes Specialized processes handle the delta for specialized topic types Base and delta DTDs Base and delta processors Base topic Base processors Task bcTask Concept Specialization-specific processors Reference bcReference

25. Summary

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

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

28. Backup Slides

29. Epic Editor with DITA Maps Manage hierarchy Create new & edit Preview HTML & PDF Check out

30. Epic Editor with DITA Topics Content edit Common elements Indexing, linking helpers

31. DITA topic example Identifier, title, and shortdesc <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> <related-links> <link href="formatstorage.dita"/> <link href="installmemory.dita"/> </related-links> </task> Properties of the topic Type-specific content body Relationships to other topics

32. A heading doesn’t have to have a topic DITA map example <map title="Tasks"> <topichead navtitle="Installing" audience="admin"> <topicmeta> <shortdesc>Install products before configuring or using them.</shortdesc> <topicmeta> <topicref href="installstorage.dita"> <topicref href="unscrewcover.dita"/> <topicref href="insertdrive.dita"/> <topicref href="replacecover.dita"/> </topicref> <topicref href="installwebserver.dita"> <topicref href="closeprograms.dita"/> <topicref href="runsetup.dita"/> <topicref href="restart.dita"/> </topicref> <topicref href="installdb.dita"> <topicref href="closeprograms.dita"/> <topicref href="runsetup.dita"/> <topicref href="restart.dita"/> </topicref> </topichead> … </map> Title and properties can be assigned in the map The map organizes a set of topics in a hierarchy A topic can appear multiple times in the hierarchy